Skip to content

@uriva/safeapp

0.2.11
Skill

Description

Build, deploy, and manage agent-native applications, dashboards, and internal tools on SafeApp..

Pending
tank install -g @uriva/safeapp

SafeApp Platform Skill

SafeApp (https://app.safescript.cc) is an agent-native, file-free, and git-free application platform where policy derives placement. Applications are collections of discrete Safescript functions stored in an entity store and manipulated via REST API (/api/v1/apps).

In SafeApp, the database IS the state — there is no double mechanism.

Canonical platform spec: https://app.safescript.cc/llms.txt. Safescript spec: https://safescript.cc/llms.txt (load the safescript skill / safescript-language-reference for full language syntax).


âš¡ Quickstart for Agents (1-Call Zero-Auth Deploy)

Option A: Single-Call Zero-Auth Deploy (Raw Safescript — Fastest)

No account or token needed to spin up a live app. POST raw Safescript directly:

POST https://app.safescript.cc/api/v1/apps?title=Leads+CRM
Content-Type: text/plain

add = (lead) => dbTransact({ namespace: "leads", patch: lead })

render = () => (
  <Card title="Leads CRM">
    <Table rows={dbQuery("leads").items} />
    <form onSubmit={add}>
      <input name="company" placeholder="Company" />
      <input name="contact" placeholder="Contact" />
      <input name="status" placeholder="Status" />
      <button type="submit">Add</button>
    </form>
  </Card>
)

Returns { "ok": true, "liveUrl": "https://app.safescript.cc/preview/leads-crm-x7k2/main", "claimUrl": "https://app.safescript.cc/claim/...", "expiresAt": "...", "adminToken": "sa_..." }. Always share both liveUrl and claimUrl with the user so they can permanently claim or lock their app!

Option B: Single-Call JSON with Pre-Seeded SQLite Data

POST https://app.safescript.cc/api/v1/apps
Content-Type: application/json

{
  "title": "Leads CRM",
  "data": {
    "leads": [
      { "company": "Wix", "contact": "Dana", "status": "Qualified" },
      { "company": "Linear", "contact": "Yael", "status": "Won" }
    ]
  },
  "code": "render = () => (<Card title='Leads CRM'><Table rows={dbQuery('leads').items} /></Card>)"
}

Use the returned adminToken (Authorization: Bearer <adminToken>) for subsequent updates (POST /api/v1/apps/:appId/functions or POST /api/v1/apps/:appId/data/:namespace). If an endpoint returns HTTP 402 (code: "UPGRADE_REQUIRED"), surface upgradeUrl (and claimUrl) directly to the user.


1. Authentication & App Access

  • Base URL: https://app.safescript.cc (or local server http://localhost:<PORT>)
  • Headers: Authorization: Bearer <TOKEN> or x-safeapp-token: <TOKEN>
  • Instant Guest Admin Session (Zero Email): POST /api/v1/auth/guest with {} → { ok: true, token: "sa_guest_..." }
  • Private App Gate: Pass "isPrivate": true on POST /api/v1/apps (or PATCH /api/v1/apps/:appId) to enforce the Turnkey Hosted Login Page on /preview and /rpc.
  • Headless User Token Minting (For Browser Testing): POST /api/v1/apps/:appId/auth/token with { "email": "admin@example.com" } → open /preview/:appId/:branch?auth_token=<userToken>.

2. Application Contract & Publishing Functions

  1. render() (or render(state)): Required. Returns a View ADT tree ({ tag, attrs, on, text, children }). Can query dbQuery("namespace").items directly; both SSR and interactive client re-renders bridge dbQuery automatically.
  2. update(state, action, payload) (or standalone action functions): Optional. Handles UI events and mutates data via dbTransact({ namespace, id, patch }) or dbDelete({ namespace, id }).
  3. initialState(): Optional. Transient client UI state (tabs, search filter). Defaults to {}.
  4. handleQueueTask(taskName, payload): Optional. Background queue worker entrypoint.

Publishing / Updating / Deleting Functions

  • Raw Safescript (Content-Type: text/plain or application/safescript): POST /api/v1/apps/:appId/functions?summary=... (or /branches/:branch/functions; add ?replace=true to replace all functions).
  • JSON (Content-Type: application/json): POST /api/v1/apps/:appId/functions with { "updates": { "render": "...", "oldFn": null }, "deleteFunctions": ["oldFn"], "summary": "..." } (or { "code": "render = () => { ... }" }).
  • Branching, Testing & Policy-Gated Merge:
    • Create branch: POST /api/v1/apps/:appId/branches with { "name": "feat-x", "fromBranch": "main" }
    • Run test* zero-arg functions: POST /api/v1/apps/:appId/branches/:branch/test
    • Auto-merge (succeeds without human review when tests pass and no new secrets/hosts were added): POST /api/v1/apps/:appId/branches/:branch/merge with { "targetBranch": "main" }
    • Read deployed functions on a branch: GET /api/v1/apps/:appId/branches/:branch/functions
    • Public RPC invocation (auto-wraps single payload into first param, enforces secret-return policy): POST /api/v1/apps/:appId/branches/:branch/rpc with { "functionName": "listItems", "args": {} }
    • Admin ad-hoc server invocation (requires adminToken with can_update_functions; accepts named { "<paramName>": ... } or single-param payload): POST /api/v1/apps/:appId/branches/:branch/run with { "functionName": "seedData", "args": {} }

3. Built-in Capability Ops

  • Database: dbQuery("leads") or dbQuery({ namespace: "leads", where: { status: "Active" } }).items, dbTransact({ namespace: "leads", id: leadId, patch: { status: "Won" } }), dbDelete({ namespace: "leads", id: leadId }).
  • Key-Value Store: kvGet("counter").value, kvSet({ key: "counter", value: 1, expireInSeconds: 3600 }), kvDelete("counter").
  • Task Queue: queueEnqueue({ queue: "default", taskName: "sync", payload: { id: "1" }, delaySeconds: 60 }).
  • Scheduled Cron Jobs: Configure via POST /api/v1/apps/:appId/crons ({ "schedule": "0 9 * * *", "functionName": "dailyDigest", "runNow": true }), GET /api/v1/apps/:appId/crons, or inline on POST /api/v1/apps ("crons": [...] or ?cron=0+9+*+*+*:dailyDigest). Supports 5-field UTC cron (*/5 * * * *) and macros (@hourly, @daily, @weekly, @every_5m).
  • Vaulted Secrets (Server-Only): Configure via POST /api/v1/apps/:appId/secrets ({ "name": "STRIPE_KEY", "allowedHosts": ["api.stripe.com"], "value": "..." }), read in server functions via readSecret("STRIPE_KEY").

4. UI Primitives & Event Bindings

Use built-in UI tag syntax (desugars statically to { tag, attrs, on, children }):

  • Page & Grid: <Page title="Pipeline" subtitle="Q4"><Grid cols={3}>...</Grid></Page>
  • Card: <Card title="Pipeline" subtitle="Q4 Deals">{children}</Card>
  • Table: <Table rows={leads} /> (auto-infers clean columns) or <Table columns={["company", "status"]} rows={leads} />
  • Badge: <Badge variant="success">Active</Badge> (success | warning | danger | info | neutral)
  • Stat: <Stat label="MRR" value="$45,200" />
  • Raw HTML: <RawHtml html="<div>...</div>" />
  • Events (onClick, onChange, onInput, onSubmit):
    • <button onClick={toggleLead} data-payload={jsonStringify({ id: lead.id })}>Toggle</button> invokes named function toggleLead (client or server RPC) and re-renders while preserving input focus.
    • <form onSubmit={addLead}><input name="company" /><button type="submit">Add</button></form> serializes <input name="..."> fields into an object payload and resets the form.

Command Palette

Search packages, docs, and navigate Tank