@ambasada/sdk 0.8.20 → 0.8.21

package/README.md

@@ -1,6 +1,6 @@
 # @ambasada/sdk
 
-The Ambasada platform client: Sign in with Ambasada, mini-app notifications, the project store, files. Node ≥ 22,
+The ambasada platform client: Sign in with ambasada, mini-app notifications, the project store, files. Node ≥ 22,
 Bun, Cloudflare Workers, Next.js route handlers. No runtime dependencies.
 
 ```ts
@@ -9,8 +9,8 @@ import { ambasada } from "@ambasada/sdk"; // AMBASADA_API_KEY, AMBASADA_API_URL
 
 | | |
 |---|---|
-| `ambasada.auth.login(req)` / `.callback(req)` / `.user(req)` / `.logout(req)` / `.shell(req)` | Sign in with Ambasada (below) |
-| `ambasada.apps.verifyWebhook(req)` / `.notify({ … })` | the Ambasada app's events and push notifications (docs/MINI-APPS.md §7) |
+| `ambasada.auth.login(req)` / `.callback(req)` / `.user(req)` / `.logout(req)` / `.shell(req)` | Sign in with ambasada (below) |
+| `ambasada.apps.verifyWebhook(req)` / `.notify({ … })` | the ambasada app's events and push notifications (docs/MINI-APPS.md §7) |
 | `ambasada.store.get(key)` / `.put(key, value)` / `.delete(key)` / `.list(prefix)` | JSON key-value, 1 MB per app |
 | `ambasada.files.put(data)` | a file at a public URL |
 | `ambasada.project()`, `ambasada.keys()` | the app's id; the API's signing keys |
@@ -25,16 +25,16 @@ The Hack A Ton economy (TON, checkout, offerings, the agent) is the add-on
 `VillageError`, `offering`, `defineCompany`, …) are still exported here, `@deprecated`, until 2.0. Note that
 `createAmbasada` returns the platform client from 0.8; selling code uses `createVillage`.
 
-## Sign in with Ambasada
+## Sign in with ambasada
 
-People sign in to your product with their Ambasada ID (OAuth 2.0 code flow + PKCE, consent screen). Zero
+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 ambasada = createAmbasada({ env });
-// GET /api/auth/login?returnTo=/path   → redirect to the Ambasada ID consent screen
+// GET /api/auth/login?returnTo=/path   → redirect to the ambasada ID consent screen
 return ambasada.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 ambasada.auth.callback(req);
@@ -45,7 +45,7 @@ return ambasada.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`
+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:
@@ -55,4 +55,4 @@ 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.
+Built by [CENTYSO](https://centyso.com) for [ambasada](https://ambasada.id). MIT.

package/dist/apps.d.ts

@@ -56,7 +56,7 @@ export interface AppNotifyInput {
     url: string;
     /** Notification tokens from `notifications_enabled`, ≤ 100 per call. */
     tokens?: string[];
-    /** Ambasada user ids, for Verified apps with the identity scope. */
+    /** ambasada user ids, for Verified apps with the identity scope. */
     users?: string[];
     /** Default "transactional", the only one Listed apps may send. */
     category?: NotificationCategory;

package/dist/auth.d.ts

@@ -1,5 +1,5 @@
 /**
- * "Sign in with Ambasada" (docs/AUTH.md): OAuth 2.0 authorization code + PKCE against Ambasada ID,
+ * "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:
@@ -13,7 +13,7 @@
  * 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.
  *
- * Silent sign-in inside the Ambasada app (docs/MINI-APPS.md §5): the page asks the shell for a short-lived
+ * Silent sign-in inside the ambasada app (docs/MINI-APPS.md §5): the page asks the shell for a short-lived
  * token (`auth.getToken()` from @ambasada/miniapp) and POSTs it here; the same session cookie comes back:
  *
  *   POST /api/auth/shell { token } → return ambasada.auth.shell(req)                      // { user } + cookie
@@ -21,11 +21,11 @@
  */
 /** 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. */
+    /** 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. */
+    /** Has the builder flag on their ambasada ID. */
     builder: boolean;
     builder_since: string | null;
     member_since: string | null;
@@ -42,7 +42,7 @@ export interface AuthConfig {
     audiences?: string[];
     /** The hub (default https://hub.ambasada.id): signs shell tokens, and has the full profile behind one (`/api/apps/profile`). */
     hubUrl?: string;
-    /** Where `/v1/auth/profile` lives (the Ambasada API). */
+    /** Where `/v1/auth/profile` lives (the ambasada API). */
     apiUrl: string;
     /** Your public origin if the Worker sees another host (behind a proxy). Default: the request's origin. */
     publicUrl?: string;
@@ -83,7 +83,7 @@ export declare function readCookie(req: WithHeaders, name: string): string | nul
  * any control character (browsers drop tabs and newlines, so "/\t/evil" would become "//evil").
  */
 export declare function safeReturnTo(value: string | null | undefined): string;
-/** Who a verified shell token is for. Name and avatar are what Ambasada ID had when the shell minted it. */
+/** Who a verified shell token is for. Name and avatar are what ambasada ID had when the shell minted it. */
 export interface ShellUser {
     user_id: string;
     name: string | null;
@@ -99,11 +99,11 @@ export declare class AmbasadaAuth {
     /** 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. */
+    /** 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 Ambasada API, sets the session cookie
+     * 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 ambasada API, sets the session cookie
      * and redirects to `returnTo`. A refused consent goes back to `returnTo` signed out.
      */
     callback(req: Request): Promise<Response>;
@@ -111,7 +111,7 @@ export declare class AmbasadaAuth {
     user(req: WithHeaders): Promise<AmbasadaUser | null>;
     /**
      * Verifies a shell token (RS256, 60 s) from the hub (`<AMBASADA_HUB_URL>/.well-known/jwks.json`, default
-     * https://hub.ambasada.id) or Ambasada ID (`<AMBASADA_AUTH_ISSUER>/.well-known/jwks.json`, the Clerk JWT template
+     * https://hub.ambasada.id) or ambasada ID (`<AMBASADA_AUTH_ISSUER>/.well-known/jwks.json`, the Clerk JWT template
      * `ambasada-miniapp`), keys cached 1 h: signature, expiry, issuer, and that its `aud` is this app (its origin or
      * id). Returns who it is, or throws `AmbasadaError("UNAUTHORIZED")`; `NOT_CONFIGURED` (503) while the issuer
      * publishes no keys.

package/dist/client.d.ts

@@ -20,7 +20,7 @@ export interface AmbasadaOptions {
      * an `AMBASADA_API` service binding there: the client calls the API through it (no zone in between, so no 522).
      */
     env?: Record<string, unknown>;
-    /** Sign in with Ambasada credentials. Default: `AMBASADA_AUTH_CLIENT_ID`, `_CLIENT_SECRET`, `_ISSUER`, and `PUBLIC_URL`. */
+    /** Sign in with ambasada credentials. Default: `AMBASADA_AUTH_CLIENT_ID`, `_CLIENT_SECRET`, `_ISSUER`, and `PUBLIC_URL`. */
     auth?: {
         clientId?: string;
         clientSecret?: string;
@@ -54,7 +54,7 @@ export interface RawResponse {
     json: unknown;
 }
 /**
- * The Ambasada client. `import { ambasada } from "@ambasada/sdk"` gives one configured from the
+ * The ambasada client. `import { ambasada } from "@ambasada/sdk"` gives one configured from the
  * environment; `createAmbasada({ env })` makes another (e.g. from a Worker's `env`).
  */
 export declare class Ambasada {
@@ -71,7 +71,7 @@ export declare class Ambasada {
     get apiUrl(): string;
     protected get apiKey(): string;
     /**
-     * Sign in with Ambasada (docs/AUTH.md): `login(req)`, `callback(req)`, `user(req)`, `logout(req)`.
+     * 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;

package/dist/define.d.ts

@@ -3,18 +3,18 @@
  * (`ambasada dev`, `deploy`, `link`, `check`). Add-ons add their own keys (the village: `idea`, `offerings`, `agent`).
  */
 /**
- * The app's Ambasada mini app (docs/MINI-APPS.md §15, decision 15.6): optional. With it, `ambasada dev` and `deploy`
+ * The app's ambasada mini app (docs/MINI-APPS.md §15, decision 15.6): optional. With it, `ambasada dev` and `deploy`
  * serve /.well-known/ambasada.json (from this and `id`, `name`, `description`), `ambasada check` runs the mini-app
- * rules on the entry, and the deploy registers the app with the Ambasada app. `ambasada miniapp enable` adds it.
+ * rules on the entry, and the deploy registers the app with the ambasada app. `ambasada miniapp enable` adds it.
  */
 export interface MiniAppConfig {
-    /** The path the Ambasada app opens: "/app" (the in-app layout under it), or "/" for the whole site. */
+    /** The path the ambasada app opens: "/app" (the in-app layout under it), or "/" for the whole site. */
     entry: string;
     /** A 1024×1024 opaque PNG, a path on the app (default "/icon.png"). */
     icon?: string;
     /** Who it is for (default "4+"). The hub refuses to register a mini app without one; above 12+ it opens only for people old enough. */
     age_rating?: "4+" | "9+" | "12+" | "17+";
-    /** How the Ambasada app shows it (default "tool"). */
+    /** How the ambasada app shows it (default "tool"). */
     kind?: "product" | "event" | "tool" | "assistant";
     /** Where people get help: "mailto:you@team.ro" or an https URL (default: the app's `support`). Needed to be Listed. */
     support?: string;
@@ -57,7 +57,7 @@ export interface AppConfig {
     product?: {
         url?: string;
     };
-    /** The mini app inside the Ambasada app, at a path of this one. Off without it. */
+    /** The mini app inside the ambasada app, at a path of this one. Off without it. */
     miniapp?: MiniAppConfig;
     /** age_rating, kind and tags, for an app with or without a mini app (the mini app's own win). */
     listing?: ListingConfig;

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 /**
- * Typed errors. Every Ambasada API failure is `{ "error": { "code", "message", ... } }` with a code
+ * Typed errors. Every ambasada API failure is `{ "error": { "code", "message", ... } }` with a code
  * from `@ambasada/protocol` (packages/protocol/src/errors.ts); the SDK turns it into an `AmbasadaError`
  * with the same `code`, so you branch on `error.code` instead of parsing messages:
  *

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 /**
- * @ambasada/sdk: the Ambasada platform client. Sign-in, mini-app notifications, the project store, files.
+ * @ambasada/sdk: the ambasada platform client. Sign-in, mini-app notifications, the project store, files.
  *
  *   import { ambasada } from "@ambasada/sdk";             // AMBASADA_API_KEY, AMBASADA_API_URL from the env
- *   const user = await ambasada.auth.user(req);            // Sign in with Ambasada (docs/AUTH.md)
+ *   const user = await ambasada.auth.user(req);            // Sign in with ambasada (docs/AUTH.md)
  *   await ambasada.apps.notify({ notification_id, title, body, url, users });   // mini-app pushes (docs/MINI-APPS.md §7)
  *   await ambasada.store.put("settings", { theme: "dark" });
  *

package/dist/platform.js

@@ -435,7 +435,7 @@ var AmbasadaAuth = class {
   settings(req) {
     const c = this.config();
     if (!c.clientId || !c.clientSecret || !c.issuer) {
-      throw new AmbasadaError("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)");
+      throw new AmbasadaError("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 {
@@ -450,7 +450,7 @@ var AmbasadaAuth = class {
       fetch: c.fetch ?? ((input, init) => fetch(input, init))
     };
   }
-  /** Redirects to Ambasada ID (consent screen) with PKCE; a short-lived signed cookie holds the state. */
+  /** 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();
@@ -470,8 +470,8 @@ var AmbasadaAuth = class {
     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 Ambasada API, sets the session cookie
+   * 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 ambasada API, sets the session cookie
    * and redirects to `returnTo`. A refused consent goes back to `returnTo` signed out.
    */
   async callback(req) {
@@ -496,9 +496,9 @@ var AmbasadaAuth = class {
       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 AmbasadaError("UNAUTHORIZED", `Ambasada ID refused the sign-in (${tokens.error ?? token.status})`, 401);
+    if (!token.ok || !tokens.access_token) throw new AmbasadaError("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 AmbasadaError("UPSTREAM_ERROR", `could not read the Ambasada profile (${res.status})`, 502);
+    if (!res.ok) throw new AmbasadaError("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 });
@@ -512,7 +512,7 @@ var AmbasadaAuth = class {
   }
   /**
    * Verifies a shell token (RS256, 60 s) from the hub (`<AMBASADA_HUB_URL>/.well-known/jwks.json`, default
-   * https://hub.ambasada.id) or Ambasada ID (`<AMBASADA_AUTH_ISSUER>/.well-known/jwks.json`, the Clerk JWT template
+   * https://hub.ambasada.id) or ambasada ID (`<AMBASADA_AUTH_ISSUER>/.well-known/jwks.json`, the Clerk JWT template
    * `ambasada-miniapp`), keys cached 1 h: signature, expiry, issuer, and that its `aud` is this app (its origin or
    * id). Returns who it is, or throws `AmbasadaError("UNAUTHORIZED")`; `NOT_CONFIGURED` (503) while the issuer
    * publishes no keys.
@@ -564,7 +564,7 @@ var AmbasadaAuth = class {
    * Answers `{ user }`.
    */
   async shell(req) {
-    if (!this.configured) throw notConfigured("this app has no Sign in with Ambasada credentials (AMBASADA_AUTH_*: on ambasada.dev after `ambasada deploy`, and under `ambasada dev`)");
+    if (!this.configured) throw notConfigured("this app has no Sign in with ambasada credentials (AMBASADA_AUTH_*: on ambasada.dev after `ambasada deploy`, and under `ambasada dev`)");
     const s = this.settings(req);
     if (req.method !== "POST") throw new AmbasadaError("INVALID_REQUEST", "POST the shell token as JSON { token }", 405);
     let token = /^Bearer\s+(.+)$/i.exec(req.headers.get("authorization") ?? "")?.[1]?.trim();
@@ -645,7 +645,7 @@ var Ambasada = class {
     return key;
   }
   /**
-   * Sign in with Ambasada (docs/AUTH.md): `login(req)`, `callback(req)`, `user(req)`, `logout(req)`.
+   * 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(() => ({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ambasada/sdk",
-  "version": "0.8.20",
-  "description": "The Ambasada platform SDK: Sign in with Ambasada, mini-app notifications, the project store, files.",
+  "version": "0.8.21",
+  "description": "The ambasada platform SDK: Sign in with ambasada, mini-app notifications, the project store, files.",
   "type": "module",
   "license": "MIT",
   "sideEffects": false,
@@ -27,7 +27,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@ambasada/village": "^0.8.20"
+    "@ambasada/village": "^0.8.21"
   },
   "devDependencies": {
     "@types/node": "^22.20.5",