{title}

[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_216":217,"_218":219},"routes/_app.x.$handle.$name",{"_96":95,"_32":44,"_104":86,"_27":105,"_13":14,"_106":-5,"_11":107,"_108":109,"_110":111,"_112":113,"_114":115,"_20":-5,"_116":-5,"_117":-5,"_118":25,"_119":120,"_121":58,"_122":-5,"_123":-5,"_124":125},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_42":43,"_32":44,"_37":45,"_46":-5,"_47":25,"_48":49,"_50":49,"_51":52,"_53":-5,"_18":54,"_55":56,"_57":58,"_59":-5,"_60":-5,"_61":62,"_63":64,"_65":-5,"_66":-5,"_67":-5,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":79,"_80":81,"_82":83,"_84":25},"version",28,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":25,"_27":28,"_29":28},"file",{"_30":31,"_32":28,"_33":20,"_34":36,"_37":38,"_39":14,"_40":41,"_24":25},"previous",{"_30":31,"_32":28,"_33":20,"_34":35},"deleted",false,"deletedHere","path","sent-messaging.md","latestPath","fileId","abdebd5a-8210-11f1-a364-1607ee4eb77e","name","fileType","content","# A userspace `sent-dm/sms` for Val Town\n\nThis page maps Sent's \"import text messaging into vals\" proposal onto the [generic userspace-proxy pattern](/generic). The punchline: **everything in the proposal is buildable today from a regular Val Town account, by Sent** — as a sponsored function like `sent-dm/sms` — with no Val Town platform work.\n\nWhat changes from the generic pattern: instead of Val Town collecting phone verification at signup, **your proxy val does the verification**, keyed to each user's Val Town identity. Same guarantees (verified ownership, opt-in consent, self-send only), different owner.\n\n```\nuser's val ──▶ sent-dm/sms (SDK) ──VT token──▶ sent-dm/sms-proxy ──▶ Sent API\n │\n ├─ /v1/me → Val Town user id\n ├─ sqlite: users (user_id → verified phone)\n ├─ sqlite: usage (rate limits)\n └─ inbound webhook → user's registered val\n```\n\n## The SDK surface\n\nOne function. The number comes from a `PHONE_NUMBER` env var, or optionally as the second argument; opt-in happens implicitly on the first send.\n\n```ts\nimport { sms } from \"https://esm.town/v/sent-dm/sms\";\n\nawait sms.send(\"⚽ Kickoff in 10 min: USA vs Japan\");\n// or, without setting the env var:\nawait sms.send(\"⚽ Kickoff in 10 min: USA vs Japan\", \"+12025551234\");\n```\n\nTo be clear about what the second argument is *not*: it is not a `to` field. **Your account can only ever text one number — your own.** The first number you opt in is bound to your Val Town account (one number per account, one account per number, enforced by the schema below). Passing a different number later doesn't send anything — it starts the opt-in flow over for the new number, which replaces the old one once its owner replies. There is no way to express texting a second recipient. And there's no separate verify/confirm step, because the first send *is* the verification:\n\n1. First `sms.send()` for a user: the proxy doesn't deliver it. Instead it texts the number an opt-in request — `\"A Val Town val wants to text you. Reply 1 to opt in.\"` — and queues the message.\n2. The user replies `1` from their phone. The inbound webhook marks the number verified and delivers the queued message.\n3. Every send after that is instant.\n\nThis reply-based flow is classic **double opt-in**, and it's a *stronger* consent record than an OTP: the opt-in lives in the carrier-visible message log itself, sent from the phone being subscribed. It also proves number ownership exactly as well — only the person holding the phone can reply.\n\n## Opt-in state: one number per Val Town user\n\nThe proxy keeps a `users` table mapping Val Town user id → exactly one phone number. `user_id` is the primary key and `phone` is `UNIQUE`, so one-number-per-user (and one-user-per-number) are schema constraints, not code paths.\n\n```ts\nimport { sqlite } from \"https://esm.town/v/std/sqlite/main.ts\";\n\nawait sqlite.execute(`CREATE TABLE IF NOT EXISTS users (\n user_id TEXT PRIMARY KEY, -- Val Town user id from /v1/me\n username TEXT NOT NULL,\n phone TEXT UNIQUE, -- E.164; UNIQUE: a number belongs to one account\n verified_at TEXT, -- set when the user replies \"1\" = consent timestamp\n claim_expires_at TEXT, -- pending claims time out (e.g. 1 hour)\n pending_message TEXT, -- the queued first message, delivered on opt-in\n opted_out_at TEXT -- set on STOP\n)`);\n```\n\nRules that keep the implicit flow safe:\n\n- **One active claim per phone.** The `UNIQUE` constraint means a second account trying to claim an already-taken (or pending) number gets a clear error instead of making the bare `\"1\"` reply ambiguous.\n- **Claims expire.** A typo'd number or an ignored opt-in request times out (`claim_expires_at`); the next send re-issues the claim. A wrong number that never replies never receives anything but the single opt-in request.\n- **Changing your number** = update the env var (or pass the new number to `send()`); the next send re-runs the same opt-in flow against the new number, replacing the old one.\n- **Rate-limit opt-in requests hard** (e.g. 3/hour per user *and* per phone) — unverified-number sends are the classic SMS-pumping target, OTP or not.\n\n## Sending: self-send enforced server-side\n\nThe SDK treating the number as your identity rather than a recipient is UX; the real enforcement is in the proxy, which only ever delivers to the one number verified for the authenticated account:\n\n```ts\n// POST /send { text, phone } — after verifyToken(...)\nconst row = await getUser(user.id);\nif (!row?.verified_at || row.phone !== body.phone) {\n // first send (or changed number): queue the message and text an opt-in request instead\n await claimNumber(user, body.phone, body.text); // enforces UNIQUE + claim expiry + opt-in rate limits\n return Response.json({ status: \"opt_in_pending\", detail: \"We texted your number — reply 1 to opt in.\" }, { status: 202 });\n}\nif (row.opted_out_at) {\n return Response.json({ error: \"This number texted STOP. Reply START to resume.\" }, { status: 403 });\n}\n\nconst { allowed, count } = await checkRateLimit(user.id, 50, 86400); // e.g. 50 msgs/day\nif (!allowed) return Response.json({ error: `Rate limit (${count}/50 per day)` }, { status: 429 });\n\nconst sentRes = await fetch(\"https://api.sent.dm/v1/messages\", {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${Deno.env.get(\"SENT_API_KEY\")}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n from: DEDICATED_NUMBER,\n to: row.phone, // proxy-controlled — never from the request\n text: body.text,\n }),\n});\n```\n\nThe client literally cannot influence the recipient. Combined with Sent's number-level STOP/HELP handling and carrier-signal monitoring, that's the whole compliance story from the PDF, implemented in ~30 lines.\n\n## Inbound replies → `onMessage`\n\nPoint the dedicated number's inbound webhook (configured in Sent) at the proxy, e.g. `POST /webhooks/sent`. The proxy:\n\n1. Verifies the webhook signature with a shared secret.\n2. Looks up the sender's phone in `users` → finds which Val Town user it belongs to.\n3. If the number has an unexpired pending claim and the reply is `1` (or `YES`): set `verified_at`, deliver `pending_message`. This is the whole opt-in confirmation — no OTP endpoint needed.\n4. Handles `STOP`/`START` keywords by setting/clearing `opted_out_at` (belt-and-suspenders; Sent also blocks at the number level).\n5. Otherwise forwards the message to that user's registered handler val.\n\nFor the handler registration, keep it prototype-simple: the user makes an HTTP val and registers its URL once:\n\n```ts\nawait sms.onMessage(\"https://steve--worldcup.web.val.run/sms\");\n```\n\nThe proxy stores that URL on the user's row and POSTs `{ body, receivedAt }` to it (with an HMAC header the SDK can verify). A fancier version could use Val Town's API to invoke a named export, but a plain webhook-to-a-val works today and matches how users already receive webhooks from Stripe, GitHub, etc.\n\n## Orgs: punt, deliberately\n\n`/v1/me` with an org-scoped token returns the org as the \"user\", so an org gets one row in `users` like anyone else — meaning **one verified number per org**, presumably a founder's or a team lead's. That's fine for a prototype: the self-send story (\"the tool texts its own builder\") is inherently personal, and per-member numbers inside orgs can come later without changing the architecture (a `users` table keyed on `(org_id, member_id)` is a migration, not a redesign).\n\n## Rate limiting specifics for SMS\n\nCopy the generic sqlite pattern, but note SMS has real per-message cost, so limit in layers:\n\n- **Per-user daily cap** (e.g. 50/day) — the generic `checkRateLimit`.\n- **Per-user burst cap** (e.g. 5/minute) — same table, smaller window; protects against a runaway cron.\n- **Global daily cap** across all users — one more COUNT without the `user_id` filter; protects your Sent bill if something goes viral.\n- **Opt-in request caps** per-user *and* per-phone-number, as above.\n\n## What Sent needs from Val Town\n\nNothing, to start. Create a `sent-dm` account, hold your own Sent API key in the proxy val's env vars, and ship. The pieces the PDF assigned to Val Town (signup-time phone verification, the `std/` namespace, routing to `onMessage`) all have userspace equivalents shown above. If usage proves out, promoting `sent-dm/sms` toward a first-party `std/messaging` is a rename, not a rewrite.\n","# A userspace `sent-dm/sms` for Val Town\n\nThis page maps Sent's \"import text messaging into vals\" proposal onto the [generic userspace-proxy pattern](/generic). The punchline: **everything in the proposal is buildable today from a regular Val Town account, by Sent** — as a sponsored function like `sent-dm/sms` — with no Val Town platform work.\n\nWhat changes from the generic pattern: instead of Val Town collecting phone verification at signup, **your proxy val does the verification**, keyed to each user's Val Town identity. Same guarantees (verified ownership, opt-in consent, self-send only), different owner.\n\n```\nuser's val ──▶ sent-dm/sms (SDK) ──VT token──▶ sent-dm/sms-proxy ──▶ Sent API\n │\n ├─ /v1/me → Val Town user id\n ├─ sqlite: users (user_id → verified phone)\n ├─ sqlite: usage (rate limits)\n └─ inbound webhook → user's registered val\n```\n\n## The SDK surface\n\nOne function. The number comes from a `PHONE_NUMBER` env var, or optionally as the second argument; opt-in happens implicitly on the first send.\n\n```ts\nimport { sms } from \"https://esm.town/v/sent-dm/sms\";\n\nawait sms.send(\"⚽ Kickoff in 10 min: USA vs Japan\");\n// or, without setting the env var:\nawait sms.send(\"⚽ Kickoff in 10 min: USA vs Japan\", \"+12025551234\");\n```\n\nTo be clear about what the second argument is *not*: it is not a `to` field. **Your account can only ever text one number — your own.** The first number you opt in is bound to your Val Town account (one number per account, one account per number, enforced by the schema below). Passing a different number later doesn't send anything — it starts the opt-in flow over for the new number, which replaces the old one once its owner replies. There is no way to express texting a second recipient. And there's no separate verify/confirm step, because the first send *is* the verification:\n\n1. First `sms.send()` for a user: the proxy doesn't deliver it. Instead it texts the number an opt-in request — `\"A Val Town val wants to text you. Reply 1 to opt in.\"` — and queues the message.\n2. The user replies `1` from their phone. The inbound webhook marks the number verified and delivers the queued message.\n3. Every send after that is instant.\n\nThis reply-based flow is classic **double opt-in**, and it's a *stronger* consent record than an OTP: the opt-in lives in the carrier-visible message log itself, sent from the phone being subscribed. It also proves number ownership exactly as well — only the person holding the phone can reply.\n\n## Opt-in state: one number per Val Town user\n\nThe proxy keeps a `users` table mapping Val Town user id → exactly one phone number. `user_id` is the primary key and `phone` is `UNIQUE`, so one-number-per-user (and one-user-per-number) are schema constraints, not code paths.\n\n```ts\nimport { sqlite } from \"https://esm.town/v/std/sqlite/main.ts\";\n\nawait sqlite.execute(`CREATE TABLE IF NOT EXISTS users (\n user_id TEXT PRIMARY KEY, -- Val Town user id from /v1/me\n username TEXT NOT NULL,\n phone TEXT UNIQUE, -- E.164; UNIQUE: a number belongs to one account\n verified_at TEXT, -- set when the user replies \"1\" = consent timestamp\n claim_expires_at TEXT, -- pending claims time out (e.g. 1 hour)\n pending_message TEXT, -- the queued first message, delivered on opt-in\n opted_out_at TEXT -- set on STOP\n)`);\n```\n\nRules that keep the implicit flow safe:\n\n- **One active claim per phone.** The `UNIQUE` constraint means a second account trying to claim an already-taken (or pending) number gets a clear error instead of making the bare `\"1\"` reply ambiguous.\n- **Claims expire.** A typo'd number or an ignored opt-in request times out (`claim_expires_at`); the next send re-issues the claim. A wrong number that never replies never receives anything but the single opt-in request.\n- **Changing your number** = update the env var (or pass the new number to `send()`); the next send re-runs the same opt-in flow against the new number, replacing the old one.\n- **Rate-limit opt-in requests hard** (e.g. 3/hour per user *and* per phone) — unverified-number sends are the classic SMS-pumping target, OTP or not.\n\n## Sending: self-send enforced server-side\n\nThe SDK treating the number as your identity rather than a recipient is UX; the real enforcement is in the proxy, which only ever delivers to the one number verified for the authenticated account:\n\n```ts\n// POST /send { text, phone } — after verifyToken(...)\nconst row = await getUser(user.id);\nif (!row?.verified_at || row.phone !== body.phone) {\n // first send (or changed number): queue the message and text an opt-in request instead\n await claimNumber(user, body.phone, body.text); // enforces UNIQUE + claim expiry + opt-in rate limits\n return Response.json({ status: \"opt_in_pending\", detail: \"We texted your number — reply 1 to opt in.\" }, { status: 202 });\n}\nif (row.opted_out_at) {\n return Response.json({ error: \"This number texted STOP. Reply START to resume.\" }, { status: 403 });\n}\n\nconst dailyCap = user.tier === \"pro\" ? 10 : 2; // tier comes free with /v1/me\nconst { allowed, count } = await checkRateLimit(user.id, dailyCap, 86400);\nif (!allowed) return Response.json({ error: `Rate limit (${count}/${dailyCap} per day)` }, { status: 429 });\n\nconst sentRes = await fetch(\"https://api.sent.dm/v1/messages\", {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${Deno.env.get(\"SENT_API_KEY\")}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n from: DEDICATED_NUMBER,\n to: row.phone, // proxy-controlled — never from the request\n text: body.text,\n }),\n});\n```\n\nThe client literally cannot influence the recipient. Combined with Sent's number-level STOP/HELP handling and carrier-signal monitoring, that's the whole compliance story from the PDF, implemented in ~30 lines.\n\n## Inbound replies → `onMessage`\n\nPoint the dedicated number's inbound webhook (configured in Sent) at the proxy, e.g. `POST /webhooks/sent`. The proxy:\n\n1. Verifies the webhook signature with a shared secret.\n2. Looks up the sender's phone in `users` → finds which Val Town user it belongs to.\n3. If the number has an unexpired pending claim and the reply is `1` (or `YES`): set `verified_at`, deliver `pending_message`. This is the whole opt-in confirmation — no OTP endpoint needed.\n4. Handles `STOP`/`START` keywords by setting/clearing `opted_out_at` (belt-and-suspenders; Sent also blocks at the number level).\n5. Otherwise forwards the message to that user's registered handler val.\n\nFor the handler registration, keep it prototype-simple: the user makes an HTTP val and registers its URL once:\n\n```ts\nawait sms.onMessage(\"https://steve--worldcup.web.val.run/sms\");\n```\n\nThe proxy stores that URL on the user's row and POSTs `{ body, receivedAt }` to it (with an HMAC header the SDK can verify). A fancier version could use Val Town's API to invoke a named export, but a plain webhook-to-a-val works today and matches how users already receive webhooks from Stripe, GitHub, etc.\n\n## Orgs: punt, deliberately\n\n`/v1/me` with an org-scoped token returns the org as the \"user\", so an org gets one row in `users` like anyone else — meaning **one verified number per org**, presumably a founder's or a team lead's. That's fine for a prototype: the self-send story (\"the tool texts its own builder\") is inherently personal, and per-member numbers inside orgs can come later without changing the architecture (a `users` table keyed on `(org_id, member_id)` is a migration, not a redesign).\n\n## Rate limiting specifics for SMS\n\nCopy the generic sqlite pattern, but note SMS has real per-message cost, so limit in layers:\n\n- **Per-user daily cap** (e.g. 50/day) — the generic `checkRateLimit`.\n- **Per-user burst cap** (e.g. 5/minute) — same table, smaller window; protects against a runaway cron.\n- **Global daily cap** across all users — one more COUNT without the `user_id` filter; protects your Sent bill if something goes viral.\n- **Opt-in request caps** per-user *and* per-phone-number, as above.\n\n## What Sent needs from Val Town\n\nNothing, to start. Create a `sent-dm` account, hold your own Sent API key in the proxy val's env vars, and ship. The pieces the PDF assigned to Val Town (signup-time phone verification, the `std/` namespace, routing to `onMessage`) all have userspace equivalents shown above. If usage proves out, promoting `sent-dm/sms` toward a first-party `std/messaging` is a rename, not a rewrite.\n","createdAt",["D",1784316303671],"branchVersion","branchId","3ab11cfd-0727-458d-8b9d-c15a0986bbad","id","e40d5cb3-97fa-4556-8afc-1dba082c8748","sent-userspace-docs",["D",1784314272065],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","Docs for Sent: building a userspace std-style proxy on Val Town","imageUrl","a0bf3b31-15a5-4d5c-880e-4b1e22c9bc18","pinnedFileId","7b11c67c-8210-11f1-9088-1607ee4eb77e","pinPreview",true,"pinMigrated","screenshotVersion","likeCount",0,"orgId","e81e7335-6d4c-4764-a902-d0962bbfa9f7","tursoName","tursoHostname","tursoMeasuredAt","pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_96":95,"_103":99},"org",{"_96":95,"_97":-5,"_98":99,"_18":54,"_100":101,"_102":25},"branch",{"_13":85,"_32":86,"_42":41,"_87":43,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":44,"_94":95},"isOwned",31,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","stevekrouse","handle","displayName","avatar","https://images.clerk.dev/uploaded/img_2PqHa2Gsy93xQrjh2w78Xu0cChW.jpeg","tier","pro","canRestrictVals","profileImageUrl","branchName","","adoptOrgId",{"_42":43,"_32":44,"_37":212,"_46":-5,"_47":25,"_48":49,"_50":49,"_51":52,"_53":-5,"_18":54,"_55":56,"_57":58,"_59":-5,"_60":-5,"_61":62,"_63":64,"_65":-5,"_66":-5,"_67":-5,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":213,"_80":214,"_82":215,"_84":25},"tree",[187,188,189,190,191,192],"files",[187,188,189,190,191,192],"counts",{"_177":62,"_178":167,"_179":62,"_180":181,"_182":183},"contents",[126,127,128,129,130,131],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_42":170,"_32":171,"_30":172,"_135":-5,"_40":41,"_39":173,"_137":58,"_37":174,"_13":167,"_33":20,"_34":175,"_24":25,"_141":-5,"_27":176},{"_42":162,"_32":163,"_30":164,"_135":-5,"_40":41,"_39":165,"_137":58,"_37":166,"_13":167,"_33":20,"_34":168,"_24":25,"_141":-5,"_27":169},{"_42":155,"_32":156,"_30":157,"_135":-5,"_40":41,"_39":158,"_137":58,"_37":159,"_13":62,"_33":139,"_34":160,"_24":25,"_141":-5,"_27":161},{"_42":147,"_32":148,"_30":56,"_135":-5,"_40":41,"_39":149,"_137":58,"_37":150,"_13":136,"_33":151,"_34":152,"_24":25,"_141":153,"_27":154},{"_42":143,"_32":28,"_30":31,"_135":-5,"_40":41,"_39":14,"_137":25,"_37":144,"_13":145,"_33":20,"_34":36,"_24":25,"_141":-5,"_27":146},{"_42":132,"_32":133,"_30":134,"_135":-5,"_40":41,"_39":136,"_137":58,"_37":138,"_13":62,"_33":139,"_34":140,"_24":25,"_141":-5,"_27":142},"9811a039-9f9b-4a5e-b85c-6413de5d8d5d","styles.ts","b828f1c0-8210-11f1-8520-1607ee4eb77e","parentId",5,"latest",["D",1784314374584],"script","export const styles = `\n * { box-sizing: border-box; }\n body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif; color: #1a202c; line-height: 1.65; }\n nav { display: flex; gap: 1.5rem; padding: 0.75rem 1.5rem; border-bottom: 1px solid #e2e8f0; font-size: 0.9rem; }\n nav a { color: #2f855a; text-decoration: none; font-weight: 500; }\n nav a:hover { text-decoration: underline; }\n nav a:last-child { margin-left: auto; color: #718096; }\n main { max-width: 46rem; margin: 0 auto; padding: 2rem 1.5rem 5rem; }\n h1 { font-size: 1.8rem; line-height: 1.25; }\n h2 { margin-top: 2.5rem; border-bottom: 1px solid #e2e8f0; padding-bottom: 0.3rem; }\n pre { background: #f7fafc; border: 1px solid #e2e8f0; border-radius: 6px; padding: 1rem; overflow-x: auto; font-size: 0.85rem; line-height: 1.5; }\n code { font-family: ui-monospace, \"SF Mono\", Menlo, monospace; font-size: 0.9em; background: #f7fafc; padding: 0.1em 0.3em; border-radius: 4px; }\n pre code { background: none; padding: 0; }\n a { color: #2b6cb0; }\n blockquote { border-left: 3px solid #cbd5e0; margin-left: 0; padding-left: 1rem; color: #4a5568; }\n`;\n","label",[133],"574b6b3f-19ee-4d8d-9ccc-882a933ba767",["D",1784316303671],15,[28],"d1523f6c-9448-4b66-9925-23cf32a9b0e7","main.tsx",20,["D",1784315962219],"http","/** @jsxImportSource https://esm.sh/hono@4/jsx */\n// HTTP entrypoint: renders the two markdown docs pages\nimport { Hono } from \"npm:hono@4\";\nimport { raw } from \"npm:hono@4/html\";\nimport { marked } from \"npm:marked@12\";\nimport { readFile, serveFile } from \"https://esm.town/v/std/utils/index.ts\";\nimport { styles } from \"./styles.ts\";\n\nconst app = new Hono();\n\nconst pages = {\n \"/\": { file: \"generic-proxy.md\", title: \"Userspace std-style services on Val Town\" },\n \"/generic\": { file: \"generic-proxy.md\", title: \"Userspace std-style services on Val Town\" },\n \"/sent\": { file: \"sent-messaging.md\", title: \"A userspace sent-dm/sms\" },\n} as const;\n\nfunction Page({ title, html }: { title: string; html: string }) {\n return (\n \n \n \n \n {title}\n {raw(``)}\n \n

Diff · v28