@ambasada/sdk 0.2.0 → 0.4.0

package/README.md

@@ -21,10 +21,39 @@ import { village } from "@ambasada/sdk"; // AMBASADA_API_KEY, AMBASADA_API_URL (
 | `village.listings.put(name, def)` / `.list()` | offerings |
 | `village.wallet()`, `village.ledger(since)`, `village.transfer(to, amount)` | money |
 | `village.agent.config/steer/transcript`, `village.market.search(q)` | agent and market (CLI) |
+| `village.auth.login(req)` / `.callback(req)` / `.user(req)` / `.logout(req)` | Sign in with Ambasada (below) |
 
 Errors are `VillageError` with `code` from `@ambasada/protocol` (`isVillageError(e, "PRICE_ABOVE_MAX")`), plus
 `ReceiptInvalidError` (402) and `WebhookInvalidError` (400). Workers: `createAmbasada({ env })`.
 
+## Sign in with Ambasada
+
+People sign in to your product with their Ambasada ID (OAuth 2.0 code flow + PKCE, consent screen). Zero
+setup on `https://<slug>.ambasada.dev`: `ambasada deploy` injects `AMBASADA_AUTH_CLIENT_ID`,
+`AMBASADA_AUTH_CLIENT_SECRET` and `AMBASADA_AUTH_ISSUER`; `ambasada dev` injects fake ones and its mock signs you in
+as "Fake Visitor". Fetch-style handlers for Workers and Next.js route handlers, WebCrypto only.
+
+```ts
+const village = createAmbasada({ env });
+// GET /api/auth/login?returnTo=/path   → redirect to the Ambasada ID consent screen
+return village.auth.login(req, { returnTo: "/", email: true }); // email: also ask for their email
+// GET /api/auth/callback               → checks state, exchanges the code, reads the profile, sets the cookie
+return village.auth.callback(req);
+// anywhere on the server
+const user = await village.auth.user(req); // AmbasadaUser | null
+// GET /api/auth/logout
+return village.auth.logout(req, { returnTo: "/" });
+```
+
+`AmbasadaUser` is `{ id, name, avatar_url, builder, builder_since, member_since, pass, email? }`: `id` is the
+stable Ambasada ID (`user_…`), `pass` is `"builder" | "visitor" | "staff" | null` for the current event, `email`
+only if you asked and they agreed. The session is an HttpOnly `SameSite=Lax` cookie (`__Host-ambasada_session`
+on https) holding the signed profile (HMAC-SHA256, key derived from the client secret), valid 7 days; no token is
+kept. `returnTo` must be a path on your site. `user()` also takes `{ headers }` (Next server components:
+`village.auth.user({ headers: await headers() })`). `village.auth.configured` says whether credentials are set.
+Override them with `createAmbasada({ auth: { clientId, clientSecret, issuer, publicUrl } })`; `PUBLIC_URL` sets the
+origin of the callback URL when the Worker sees another host. More: docs/AUTH.md.
+
 `pnpm build` writes `dist/` (one ESM file + `.d.ts`); `publishConfig` points the published package at it.
 
 Built by [CENTYSO](https://centyso.com) for [Ambasada](https://ambasada.id). MIT.

package/dist/auth.d.ts

@@ -0,0 +1,95 @@
+/**
+ * "Sign in with Ambasada" (docs/AUTH.md): OAuth 2.0 authorization code + PKCE against Ambasada ID,
+ * for products hosted at https://<slug>.ambasada.dev. The deploy injects AMBASADA_AUTH_CLIENT_ID,
+ * AMBASADA_AUTH_CLIENT_SECRET and AMBASADA_AUTH_ISSUER; `ambasada dev` injects fake ones that point at
+ * the mock. Four fetch handlers, WebCrypto only, no dependencies:
+ *
+ *   GET /api/auth/login     → return village.auth.login(req, { returnTo: "/" })
+ *   GET /api/auth/callback  → return village.auth.callback(req)
+ *   GET /api/auth/logout    → return village.auth.logout(req)
+ *   anywhere                → const user = await village.auth.user(req)   // AmbasadaUser | null
+ *
+ * The session is an HttpOnly cookie holding the signed public profile (HMAC-SHA256 under a key
+ * derived from the client secret), host-only (`__Host-` on https), so no other *.ambasada.dev product
+ * can read, set or forge it. No access token is kept.
+ */
+/** The person signed in, as `GET /v1/auth/profile` returns them. */
+export interface AmbasadaUser {
+    /** Ambasada ID user id (`user_…`): stable, use it as your user key. */
+    id: string;
+    name: string | null;
+    avatar_url: string | null;
+    /** Has the builder flag on their Ambasada ID. */
+    builder: boolean;
+    builder_since: string | null;
+    member_since: string | null;
+    /** Their pass at the current event, if any. */
+    pass: "builder" | "visitor" | "staff" | null;
+    /** Only when you asked for it (`login(req, { email: true })`) and they agreed. */
+    email?: string | null;
+}
+export interface AuthConfig {
+    clientId?: string;
+    clientSecret?: string;
+    issuer?: string;
+    /** Where `/v1/auth/profile` lives (the village API). */
+    apiUrl: string;
+    /** Your public origin if the Worker sees another host (behind a proxy). Default: the request's origin. */
+    publicUrl?: string;
+    fetch?: typeof fetch;
+}
+export interface LoginOptions {
+    /** Path on your site to land on after signing in (default "/"). Only same-site paths are honored. */
+    returnTo?: string;
+    /** Also ask for their email (the consent screen says so). */
+    email?: boolean;
+}
+export declare const AUTH_PATHS: {
+    readonly login: "/api/auth/login";
+    readonly callback: "/api/auth/callback";
+    readonly logout: "/api/auth/logout";
+};
+/** How long a sign-in lasts (the cookie holds a profile snapshot; signing in again refreshes it). */
+export declare const SESSION_TTL_S: number;
+export declare function b64url(bytes: Uint8Array): string;
+/** PKCE (RFC 7636): a random verifier and its S256 challenge. */
+export declare function pkce(): Promise<{
+    verifier: string;
+    challenge: string;
+}>;
+export declare function pkceChallenge(verifier: string): Promise<string>;
+/** `<payload>.<signature>`, both base64url; the payload is JSON with `exp` (seconds). */
+export declare function signCookie(secret: string, purpose: string, payload: Record<string, unknown>): Promise<string>;
+/** The payload if the signature is ours and it has not expired; null otherwise. */
+export declare function verifyCookie<T extends {
+    exp: number;
+}>(secret: string, purpose: string, value: string | null | undefined, now?: number): Promise<T | null>;
+/** A fetch `Request`, or anything with its headers (Next: `{ headers: await headers() }`). */
+export type WithHeaders = Pick<Request, "headers">;
+export declare function readCookie(req: WithHeaders, name: string): string | null;
+/**
+ * A relative path on this site, or "/". No open redirects: "//evil", "/\\evil", "https://…" are refused, and so is
+ * any control character (browsers drop tabs and newlines, so "/\t/evil" would become "//evil").
+ */
+export declare function safeReturnTo(value: string | null | undefined): string;
+export declare class AmbasadaAuth {
+    private readonly config;
+    constructor(config: () => AuthConfig);
+    /** True when the product has credentials (hosted on ambasada.dev, or `ambasada dev`). */
+    get configured(): boolean;
+    private settings;
+    /** Redirects to Ambasada ID (consent screen) with PKCE; a short-lived signed cookie holds the state. */
+    login(req: Request, options?: LoginOptions): Promise<Response>;
+    /**
+     * Ambasada ID sends the person back here: checks the state, exchanges the code (with the PKCE
+     * verifier and the client secret), reads their profile from the village, sets the session cookie
+     * and redirects to `returnTo`. A refused consent goes back to `returnTo` signed out.
+     */
+    callback(req: Request): Promise<Response>;
+    /** Whoever is signed in on this request, or null (also null when sign-in is not set up). */
+    user(req: WithHeaders): Promise<AmbasadaUser | null>;
+    /** Clears the session and redirects to `returnTo` (default "/"). Signs out of this product only. */
+    logout(req: Request, options?: {
+        returnTo?: string;
+    }): Response;
+}

package/dist/client.d.ts

@@ -1,5 +1,6 @@
+import { AmbasadaAuth } from "./auth.js";
 import { type IncomingRequest } from "./receipt.js";
-import type { AgentConfigInput, BuyOptions, BuyResult, ChatRequest, ChatResponse, CheckoutInput, CheckoutReceiptClaims, CheckoutSession, FileOptions, ImageRequest, ImageResult, Jwk, LedgerPage, Listing, ListingInput, MarketOffering, PaidCall, PaymentLink, PaymentLinkInput, ToolListing, ToolResult, TranscriptEntry, TransferOptions, Wallet, WebhookDelivery, WebhookEvent } from "./types.js";
+import type { AgentConfigInput, BuyOptions, BuyResult, ChatRequest, ChatResponse, CheckoutInput, CheckoutReceiptClaims, CheckoutSession, FileOptions, StoredFile, StoreList, StoreWrite, ImageRequest, ImageResult, Jwk, LedgerPage, Listing, ListingInput, MarketOffering, PaidCall, PaymentLink, PaymentLinkInput, ToolListing, ToolResult, TranscriptEntry, TransferOptions, Wallet, WebhookDelivery, WebhookEvent } from "./types.js";
 export declare const DEFAULT_API_URL = "https://hackaton.ambasada.id";
 export declare const DEFAULT_MODEL = "deepseek-v4.1-flash";
 export interface VillageOptions {
@@ -19,6 +20,13 @@ export interface VillageOptions {
     timeoutMs?: number;
     /** Extra env source, e.g. a Worker's `env`. Default: `process.env` where it exists. */
     env?: Record<string, unknown>;
+    /** Sign in with Ambasada credentials. Default: `AMBASADA_AUTH_CLIENT_ID`, `_CLIENT_SECRET`, `_ISSUER`, and `PUBLIC_URL`. */
+    auth?: {
+        clientId?: string;
+        clientSecret?: string;
+        issuer?: string;
+        publicUrl?: string;
+    };
 }
 export interface VerifyReceiptOptions {
     /** Pin the offering name (`translate`), so a receipt for another of your offerings is refused. */
@@ -40,6 +48,11 @@ export declare class Village {
     private env;
     get apiUrl(): string;
     private get apiKey();
+    /**
+     * Sign in with Ambasada (docs/AUTH.md): `login(req)`, `callback(req)`, `user(req)`, `logout(req)`.
+     * Credentials come with the deploy to ambasada.dev, and from `ambasada dev` locally.
+     */
+    readonly auth: AmbasadaAuth;
     private send;
     private call;
     /** Your company id (from options, `AMBASADA_COMPANY`, or the wallet the API key belongs to). */
@@ -128,12 +141,24 @@ export declare class Village {
     };
     readonly files: {
         /**
-         * Stores bytes, a Blob, or a URL to copy, for the event. Returns a public URL other products can fetch.
-         * (`POST /v1/files`: assumed route; the utilities stream serves `GET /files/:id`.)
+         * Stores bytes, a Blob, or a URL to copy, for the event (`POST /v1/files`, 0.1 TON). Returns a
+         * public URL other products can fetch.
          */
-        put: (data: Uint8Array | ArrayBuffer | Blob | string, options?: FileOptions) => Promise<{
-            url: string;
-        }>;
+        put: (data: Uint8Array | ArrayBuffer | Blob | string, options?: FileOptions) => Promise<StoredFile>;
+    };
+    /**
+     * Your company's JSON key-value store (`/v1/store`): 1 MB per company (keys + values), free. State for
+     * a hosted product that needs no database.
+     */
+    readonly store: {
+        /** The value, or null when the key is not set. */
+        get: <T = unknown>(key: string) => Promise<T | null>;
+        /** Saves any JSON value (fails with INVALID_REQUEST when the store would pass 1 MB). */
+        set: (key: string, value: unknown) => Promise<StoreWrite>;
+        /** True when the key existed. */
+        delete: (key: string) => Promise<boolean>;
+        /** Keys (up to 1000, optionally under a prefix) and how much of the 1 MB is used. */
+        list: (prefix?: string) => Promise<StoreList>;
     };
     readonly listings: {
         /** Creates or updates an offering (price changes are versioned). */

package/dist/index.d.ts

@@ -4,6 +4,7 @@
  *   import { village } from "@ambasada/sdk";             // AMBASADA_API_KEY, AMBASADA_API_URL from the env
  *   const { url } = await village.checkout({ amount: 3, description: "Coffee", success_url });
  *   export const POST = village.sell("translate", async ({ text, to }) => ({ text: await village.llm(`Translate to ${to}: ${text}`) }));
+ *   const user = await village.auth.user(req);            // Sign in with Ambasada (docs/AUTH.md)
  *
  * Works in Node ≥ 22, Bun, Cloudflare Workers (`createAmbasada({ env })`) and Next.js route handlers.
  */
@@ -16,6 +17,8 @@ export { verifyWebhookPayload, webhookHeaders, generateWebhookSecret, WEBHOOK_HE
 export { RECEIPT_HEADER, readIncoming, verifyCallReceipt, verifyCheckoutReceiptToken } from "./receipt.js";
 export type { IncomingRequest } from "./receipt.js";
 export { defineCompany, offering } from "./define.js";
+export { AmbasadaAuth, AUTH_PATHS, SESSION_TTL_S } from "./auth.js";
+export type { AmbasadaUser, AuthConfig, LoginOptions, WithHeaders } from "./auth.js";
 export type { CompanyConfig, OfferingDef } from "./define.js";
 /** The default client, configured from the environment at call time. */
 export declare const village: Village;

package/dist/index.js

@@ -1,4 +1,4 @@
-// src/errors.ts
+// ../sdk/src/errors.ts
 var ERROR_STATUS = {
   // EXCHANGE.md §5 vocabulary
   INSUFFICIENT_FUNDS: 402,
@@ -102,6 +102,188 @@ function errorFromResponse(status, body, fallback) {
   return new VillageError(code, fallback, status);
 }
 
+// ../sdk/src/auth.ts
+var AUTH_PATHS = { login: "/api/auth/login", callback: "/api/auth/callback", logout: "/api/auth/logout" };
+var SESSION_TTL_S = 7 * 24 * 3600;
+var STATE_TTL_S = 600;
+var SESSION_COOKIE = "ambasada_session";
+var STATE_COOKIE = "ambasada_auth";
+var enc = new TextEncoder();
+function b64url(bytes) {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromB64url(text) {
+  const s = atob(text.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((text.length + 3) % 4));
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+  return out;
+}
+var random = (n) => b64url(crypto.getRandomValues(new Uint8Array(n)));
+async function pkce() {
+  const verifier = random(32);
+  return { verifier, challenge: await pkceChallenge(verifier) };
+}
+async function pkceChallenge(verifier) {
+  return b64url(new Uint8Array(await crypto.subtle.digest("SHA-256", enc.encode(verifier))));
+}
+var keys = /* @__PURE__ */ new Map();
+function cookieKey(secret, purpose) {
+  const id = `${purpose}
+${secret}`;
+  let key = keys.get(id);
+  if (!key) {
+    key = crypto.subtle.importKey("raw", enc.encode(secret), "HKDF", false, ["deriveKey"]).then(
+      (ikm) => crypto.subtle.deriveKey(
+        { name: "HKDF", hash: "SHA-256", salt: enc.encode("ambasada auth cookie v1"), info: enc.encode(purpose) },
+        ikm,
+        { name: "HMAC", hash: "SHA-256", length: 256 },
+        false,
+        ["sign", "verify"]
+      )
+    );
+    keys.set(id, key);
+  }
+  return key;
+}
+async function signCookie(secret, purpose, payload) {
+  const body = b64url(enc.encode(JSON.stringify(payload)));
+  const sig = await crypto.subtle.sign("HMAC", await cookieKey(secret, purpose), enc.encode(body));
+  return `${body}.${b64url(new Uint8Array(sig))}`;
+}
+async function verifyCookie(secret, purpose, value, now = Date.now()) {
+  if (!value) return null;
+  const [body, sig, extra] = value.split(".");
+  if (!body || !sig || extra !== void 0) return null;
+  try {
+    const ok = await crypto.subtle.verify("HMAC", await cookieKey(secret, purpose), fromB64url(sig), enc.encode(body));
+    if (!ok) return null;
+    const payload = JSON.parse(new TextDecoder().decode(fromB64url(body)));
+    return typeof payload.exp === "number" && payload.exp * 1e3 > now ? payload : null;
+  } catch {
+    return null;
+  }
+}
+function readCookie(req, name) {
+  for (const part of (req.headers.get("cookie") ?? "").split(";")) {
+    const i = part.indexOf("=");
+    if (i > 0 && part.slice(0, i).trim() === name) return part.slice(i + 1).trim();
+  }
+  return null;
+}
+var cookieName = (base, secure) => secure ? `__Host-${base}` : base;
+var readOurCookie = (req, base) => readCookie(req, cookieName(base, true)) ?? readCookie(req, base);
+function setCookie(base, value, secure, maxAge) {
+  return `${cookieName(base, secure)}=${value}; Path=/; Max-Age=${maxAge}; HttpOnly; SameSite=Lax${secure ? "; Secure" : ""}`;
+}
+function safeReturnTo(value) {
+  if (!value || !value.startsWith("/") || value.startsWith("//") || value.startsWith("/\\") || /[\u0000-\u001f\u007f]/.test(value)) return "/";
+  return value;
+}
+function redirect(location, cookies = []) {
+  const headers = new Headers({ location, "cache-control": "no-store" });
+  for (const c of cookies) headers.append("set-cookie", c);
+  return new Response(null, { status: 303, headers });
+}
+var AmbasadaAuth = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  /** True when the product has credentials (hosted on ambasada.dev, or `ambasada dev`). */
+  get configured() {
+    const c = this.config();
+    return !!(c.clientId && c.clientSecret && c.issuer);
+  }
+  settings(req) {
+    const c = this.config();
+    if (!c.clientId || !c.clientSecret || !c.issuer) {
+      throw new VillageError("CONFIG", "Sign in with Ambasada is not set up: it works on https://<slug>.ambasada.dev after `ambasada deploy`, and locally under `ambasada dev` (AMBASADA_AUTH_CLIENT_ID / _SECRET / _ISSUER)");
+    }
+    const origin = (c.publicUrl ? new URL(c.publicUrl) : new URL(req.url)).origin;
+    return {
+      clientId: c.clientId,
+      clientSecret: c.clientSecret,
+      issuer: c.issuer.replace(/\/+$/, ""),
+      apiUrl: c.apiUrl.replace(/\/+$/, ""),
+      origin,
+      secure: origin.startsWith("https:"),
+      redirectUri: `${origin}${AUTH_PATHS.callback}`,
+      // Called as a plain function: workerd refuses `fetch` invoked as a method of another object.
+      fetch: c.fetch ?? ((input, init) => fetch(input, init))
+    };
+  }
+  /** Redirects to Ambasada ID (consent screen) with PKCE; a short-lived signed cookie holds the state. */
+  async login(req, options = {}) {
+    const s = this.settings(req);
+    const { verifier, challenge } = await pkce();
+    const state = random(16);
+    const returnTo = safeReturnTo(options.returnTo ?? new URL(req.url).searchParams.get("returnTo"));
+    const url = new URL(`${s.issuer}/oauth/authorize`);
+    url.search = new URLSearchParams({
+      response_type: "code",
+      client_id: s.clientId,
+      redirect_uri: s.redirectUri,
+      scope: options.email ? "openid profile email" : "openid profile",
+      state,
+      code_challenge: challenge,
+      code_challenge_method: "S256"
+    }).toString();
+    const value = await signCookie(s.clientSecret, "state", { state, verifier, returnTo, exp: Math.floor(Date.now() / 1e3) + STATE_TTL_S });
+    return redirect(url.toString(), [setCookie(STATE_COOKIE, value, s.secure, STATE_TTL_S)]);
+  }
+  /**
+   * Ambasada ID sends the person back here: checks the state, exchanges the code (with the PKCE
+   * verifier and the client secret), reads their profile from the village, sets the session cookie
+   * and redirects to `returnTo`. A refused consent goes back to `returnTo` signed out.
+   */
+  async callback(req) {
+    const s = this.settings(req);
+    const params = new URL(req.url).searchParams;
+    const clear = setCookie(STATE_COOKIE, "", s.secure, 0);
+    const saved = await verifyCookie(s.clientSecret, "state", readOurCookie(req, STATE_COOKIE));
+    if (!saved || !params.get("state") || params.get("state") !== saved.state) {
+      throw new VillageError("UNAUTHORIZED", "sign-in expired or was started elsewhere: try again", 400);
+    }
+    const returnTo = safeReturnTo(saved.returnTo);
+    if (params.get("error")) return redirect(returnTo, [clear]);
+    const code = params.get("code");
+    if (!code) throw new VillageError("INVALID_REQUEST", "no authorization code", 400);
+    const token = await s.fetch(`${s.issuer}/oauth/token`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/x-www-form-urlencoded",
+        accept: "application/json",
+        authorization: `Basic ${btoa(`${encodeURIComponent(s.clientId)}:${encodeURIComponent(s.clientSecret)}`)}`
+      },
+      body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: s.redirectUri, code_verifier: saved.verifier })
+    });
+    const tokens = await token.json().catch(() => ({}));
+    if (!token.ok || !tokens.access_token) throw new VillageError("UNAUTHORIZED", `Ambasada ID refused the sign-in (${tokens.error ?? token.status})`, 401);
+    const res = await s.fetch(`${s.apiUrl}/v1/auth/profile`, { headers: { authorization: `Bearer ${tokens.access_token}`, accept: "application/json" } });
+    if (!res.ok) throw new VillageError("UPSTREAM_ERROR", `could not read the Ambasada profile (${res.status})`, 502);
+    const user = await res.json();
+    const exp = Math.floor(Date.now() / 1e3) + SESSION_TTL_S;
+    const session = await signCookie(s.clientSecret, "session", { user, exp });
+    return redirect(returnTo, [clear, setCookie(SESSION_COOKIE, session, s.secure, SESSION_TTL_S)]);
+  }
+  /** Whoever is signed in on this request, or null (also null when sign-in is not set up). */
+  async user(req) {
+    const secret = this.config().clientSecret;
+    if (!this.configured || !secret) return null;
+    return (await verifyCookie(secret, "session", readOurCookie(req, SESSION_COOKIE)))?.user ?? null;
+  }
+  /** Clears the session and redirects to `returnTo` (default "/"). Signs out of this product only. */
+  logout(req, options = {}) {
+    const url = new URL(req.url);
+    const publicUrl = this.config().publicUrl;
+    const secure = (publicUrl ? new URL(publicUrl) : url).protocol === "https:";
+    const returnTo = safeReturnTo(options.returnTo ?? url.searchParams.get("returnTo"));
+    return redirect(returnTo, [setCookie(SESSION_COOKIE, "", secure, 0)]);
+  }
+};
+
 // ../protocol/src/encoding.ts
 var encoder = new TextEncoder();
 var decoder = new TextDecoder();
@@ -184,8 +366,8 @@ async function verifySigned(token, options) {
   }
   if (header2.alg !== "EdDSA") throw new ReceiptError("malformed", `unsupported alg ${header2.alg}`);
   if (typeof claims !== "object" || claims === null) throw new ReceiptError("malformed", "receipt claims are not an object");
-  const keys = typeof options.keys === "function" ? await options.keys() : options.keys;
-  const jwk = keys.find((k) => (k.kid ?? k.x.slice(0, 16)) === header2.kid) ?? (keys.length === 1 && !header2.kid ? keys[0] : void 0);
+  const keys2 = typeof options.keys === "function" ? await options.keys() : options.keys;
+  const jwk = keys2.find((k) => (k.kid ?? k.x.slice(0, 16)) === header2.kid) ?? (keys2.length === 1 && !header2.kid ? keys2[0] : void 0);
   if (!jwk) throw new ReceiptError("unknown_key", `no village key with kid ${header2.kid}`);
   const key = await crypto.subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: jwk.x }, ED25519, false, ["verify"]);
   const ok = await crypto.subtle.verify(ED25519, key, fromBase64url(signaturePart), utf8(`${headerPart}.${payloadPart}`));
@@ -278,7 +460,7 @@ function fromStdBase64(text) {
   return bytes;
 }
 
-// src/webhook.ts
+// ../sdk/src/webhook.ts
 function getHeader(headers, name) {
   if (typeof headers.get === "function") return headers.get(name);
   const record = headers;
@@ -309,7 +491,7 @@ async function verifyWebhookPayload(secret, headers, body, options = {}) {
   return { id: plain["webhook-id"], type: String(parsed.type), timestamp: String(parsed.timestamp ?? ""), data: parsed.data };
 }
 
-// src/receipt.ts
+// ../sdk/src/receipt.ts
 var RECEIPT_HEADER2 = "x-village-receipt";
 async function readIncoming(req) {
   if (typeof req.clone === "function" && typeof req.arrayBuffer === "function") {
@@ -394,7 +576,7 @@ function concat(chunks) {
   return out;
 }
 
-// src/client.ts
+// ../sdk/src/client.ts
 var DEFAULT_API_URL = "https://hackaton.ambasada.id";
 var DEFAULT_MODEL = "deepseek-v4.1-flash";
 function processEnv() {
@@ -434,6 +616,18 @@ var Village = class {
     if (!key) throw new VillageError("CONFIG", "no API key: set AMBASADA_API_KEY (from the village app, or `ambasada login`) or pass { apiKey }");
     return key;
   }
+  /**
+   * Sign in with Ambasada (docs/AUTH.md): `login(req)`, `callback(req)`, `user(req)`, `logout(req)`.
+   * Credentials come with the deploy to ambasada.dev, and from `ambasada dev` locally.
+   */
+  auth = new AmbasadaAuth(() => ({
+    clientId: this.options.auth?.clientId ?? this.env("AMBASADA_AUTH_CLIENT_ID"),
+    clientSecret: this.options.auth?.clientSecret ?? this.env("AMBASADA_AUTH_CLIENT_SECRET"),
+    issuer: this.options.auth?.issuer ?? this.env("AMBASADA_AUTH_ISSUER"),
+    publicUrl: this.options.auth?.publicUrl ?? this.env("PUBLIC_URL"),
+    apiUrl: this.apiUrl,
+    fetch: this.options.fetch
+  }));
   // ── HTTP ──────────────────────────────────────────────────────────────────
   async send(method, path, opts = {}) {
     const url = new URL(this.apiUrl + path);
@@ -693,8 +887,8 @@ var Village = class {
   };
   files = {
     /**
-     * Stores bytes, a Blob, or a URL to copy, for the event. Returns a public URL other products can fetch.
-     * (`POST /v1/files`: assumed route; the utilities stream serves `GET /files/:id`.)
+     * Stores bytes, a Blob, or a URL to copy, for the event (`POST /v1/files`, 0.1 TON). Returns a
+     * public URL other products can fetch.
      */
     put: (data, options = {}) => {
       const query = { ttl_seconds: options.ttlSeconds };
@@ -703,6 +897,30 @@ var Village = class {
       return this.call("POST", "/v1/files", { raw: data, headers: { "content-type": contentType }, query });
     }
   };
+  /**
+   * Your company's JSON key-value store (`/v1/store`): 1 MB per company (keys + values), free. State for
+   * a hosted product that needs no database.
+   */
+  store = {
+    /** The value, or null when the key is not set. */
+    get: async (key) => {
+      try {
+        return (await this.call("GET", `/v1/store/${encodeURIComponent(key)}`)).value;
+      } catch (error) {
+        if (error instanceof VillageError && error.status === 404) return null;
+        throw error;
+      }
+    },
+    /** Saves any JSON value (fails with INVALID_REQUEST when the store would pass 1 MB). */
+    set: (key, value) => {
+      if (value === void 0) throw new VillageError("INVALID_REQUEST", "store.set needs a JSON value (use store.delete to remove a key)");
+      return this.call("PUT", `/v1/store/${encodeURIComponent(key)}`, { body: value });
+    },
+    /** True when the key existed. */
+    delete: async (key) => (await this.call("DELETE", `/v1/store/${encodeURIComponent(key)}`)).deleted,
+    /** Keys (up to 1000, optionally under a prefix) and how much of the 1 MB is used. */
+    list: (prefix) => this.call("GET", "/v1/store", { query: { prefix } })
+  };
   // ── listings, wallet, ledger ──────────────────────────────────────────────
   listings = {
     /** Creates or updates an offering (price changes are versioned). */
@@ -742,10 +960,10 @@ function cachedKeys(load, ttlMs = 10 * 6e4) {
   let cached;
   return () => {
     if (!cached || Date.now() - cached.at > ttlMs) {
-      const keys = load();
-      const entry = { at: Date.now(), keys };
+      const keys2 = load();
+      const entry = { at: Date.now(), keys: keys2 };
       cached = entry;
-      keys.catch(() => {
+      keys2.catch(() => {
         if (cached === entry) cached = void 0;
       });
     }
@@ -756,7 +974,7 @@ function createAmbasada(options = {}) {
   return new Village(options);
 }
 
-// src/define.ts
+// ../sdk/src/define.ts
 function defineCompany(config) {
   return config;
 }
@@ -766,15 +984,18 @@ function offering(def) {
   return def;
 }
 
-// src/index.ts
+// ../sdk/src/index.ts
 var village = new Village();
 var index_default = village;
 export {
+  AUTH_PATHS,
+  AmbasadaAuth,
   DEFAULT_API_URL,
   DEFAULT_MODEL,
   ERROR_STATUS,
   RECEIPT_HEADER2 as RECEIPT_HEADER,
   ReceiptInvalidError,
+  SESSION_TTL_S,
   Village,
   VillageError,
   WEBHOOK_HEADERS,

package/dist/types.d.ts

@@ -218,6 +218,31 @@ export interface FileOptions {
     contentType?: string;
     ttlSeconds?: number;
 }
+/** `POST /v1/files` (0.1 TON a file). */
+export interface StoredFile {
+    id: string;
+    url: string;
+    size?: number;
+    content_type?: string;
+    cost?: number;
+    call_id?: string;
+}
+export interface StoreKey {
+    key: string;
+    size: number;
+    updated_at: string;
+}
+export interface StoreList {
+    keys: StoreKey[];
+    used_bytes: number;
+    limit_bytes: number;
+}
+export interface StoreWrite {
+    key: string;
+    size: number;
+    used_bytes: number;
+    limit_bytes: number;
+}
 /** Offering field schema shorthand: `{ text: "string", to: "string", tone: "string?" }`. */
 export type FieldSchema = Record<string, string>;
 export interface ListingInput {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ambasada/sdk",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "TypeScript SDK for the Hack A Ton village: Checkout, webhooks, receipts, Pay, needs, LLM, images, tools, files, listings, wallet.",
   "type": "module",
   "license": "MIT",