@uriva/safeapp
0.2.11Description
Build, deploy, and manage agent-native applications, dashboards, and internal tools on SafeApp..
tank install -g @uriva/safeappSafeApp 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 serverhttp://localhost:<PORT>) - Headers:
Authorization: Bearer <TOKEN>orx-safeapp-token: <TOKEN> - Instant Guest Admin Session (Zero Email):
POST /api/v1/auth/guestwith{}→{ ok: true, token: "sa_guest_..." } - Private App Gate: Pass
"isPrivate": trueonPOST /api/v1/apps(orPATCH /api/v1/apps/:appId) to enforce the Turnkey Hosted Login Page on/previewand/rpc. - Headless User Token Minting (For Browser Testing):
POST /api/v1/apps/:appId/auth/tokenwith{ "email": "admin@example.com" }→ open/preview/:appId/:branch?auth_token=<userToken>.
2. Application Contract & Publishing Functions
render()(orrender(state)): Required. Returns a View ADT tree ({ tag, attrs, on, text, children }). Can querydbQuery("namespace").itemsdirectly; both SSR and interactive client re-renders bridgedbQueryautomatically.update(state, action, payload)(or standalone action functions): Optional. Handles UI events and mutates data viadbTransact({ namespace, id, patch })ordbDelete({ namespace, id }).initialState(): Optional. Transient client UI state (tabs, search filter). Defaults to{}.handleQueueTask(taskName, payload): Optional. Background queue worker entrypoint.
Publishing / Updating / Deleting Functions
- Raw Safescript (
Content-Type: text/plainorapplication/safescript):POST /api/v1/apps/:appId/functions?summary=...(or/branches/:branch/functions; add?replace=trueto replace all functions). - JSON (
Content-Type: application/json):POST /api/v1/apps/:appId/functionswith{ "updates": { "render": "...", "oldFn": null }, "deleteFunctions": ["oldFn"], "summary": "..." }(or{ "code": "render = () => { ... }" }). - Branching, Testing & Policy-Gated Merge:
- Create branch:
POST /api/v1/apps/:appId/brancheswith{ "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/mergewith{ "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/rpcwith{ "functionName": "listItems", "args": {} } - Admin ad-hoc server invocation (requires
adminTokenwithcan_update_functions; accepts named{ "<paramName>": ... }or single-param payload):POST /api/v1/apps/:appId/branches/:branch/runwith{ "functionName": "seedData", "args": {} }
- Create branch:
3. Built-in Capability Ops
- Database:
dbQuery("leads")ordbQuery({ 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 onPOST /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 viareadSecret("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 functiontoggleLead(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.