@ambasada/sdk 0.8.10 → 0.8.12

package/dist/auth.d.ts

@@ -40,7 +40,7 @@ export interface AuthConfig {
     issuer?: string;
     /** Who a shell token must be for (`aud`): your app id and origin. The request's origin is added in `shell()`. */
     audiences?: string[];
-    /** The hub, for the full profile behind a shell token (`/api/apps/profile`). */
+    /** 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). */
     apiUrl: string;
@@ -110,9 +110,11 @@ export declare class AmbasadaAuth {
     /** Whoever is signed in on this request, or null (also null when sign-in is not set up). */
     user(req: WithHeaders): Promise<AmbasadaUser | null>;
     /**
-     * Verifies a shell token (Clerk JWT template `ambasada-miniapp`, RS256, 60 s) against
-     * `<AMBASADA_AUTH_ISSUER>/.well-known/jwks.json` (cached 1 h): signature, expiry, issuer, and that its `aud`
-     * is this app (its id or origin). Returns who it is, or throws `AmbasadaError("UNAUTHORIZED")`.
+     * 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
+     * `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.
      */
     verifyShellToken(token: string, options?: {
         audience?: string | string[];

package/dist/define.d.ts

@@ -31,6 +31,19 @@ export interface MiniAppConfig {
     scopes?: ("identity" | "notifications")[];
     visibility?: "public" | "builders" | "unlisted" | `event:${string}`;
 }
+/**
+ * How the app is listed, whether or not it has a mini app (dry run 7 nit d: with the mini app off there was nowhere
+ * for these). The mini app's own `age_rating`, `kind` and `tags` win; these are its defaults, and `miniapp disable`
+ * keeps them here.
+ */
+export interface ListingConfig {
+    /** Who it is for: "4+", "9+", "12+" or "17+" (the mini app's default "4+"). */
+    age_rating?: MiniAppConfig["age_rating"];
+    /** What it is: "product", "event", "tool" or "assistant" (the mini app's default "tool"). */
+    kind?: MiniAppConfig["kind"];
+    /** Up to 5 search words. */
+    tags?: string[];
+}
 export interface AppConfig {
     /** The app's slug (lowercase): it lives at https://<id>.ambasada.dev. */
     id: string;
@@ -46,6 +59,8 @@ export interface AppConfig {
     };
     /** 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;
     /** Add-ons to load besides the ones found in node_modules (package names, e.g. "@ambasada/village"). */
     addons?: string[];
 }

package/dist/errors.d.ts

@@ -47,6 +47,8 @@ export declare const ERROR_STATUS: {
     readonly CAP_TOOLS_RATE: 429;
     readonly NETWORK: 0;
     readonly CONFIG: 0;
+    /** A platform feature this app relies on is not switched on yet (silent sign-in before the hub has keys). */
+    readonly NOT_CONFIGURED: 503;
     readonly RECEIPT_INVALID: 402;
     readonly WEBHOOK_INVALID: 400;
 };
@@ -63,6 +65,8 @@ export interface ErrorDetails {
     upstream_status?: number;
     /** APPROVAL_REQUIRED: retry with `{ approval: approvalId }` once the team approved it. */
     approval_id?: string;
+    /** CAP_TOOLS_RATE, TOOL_UNAVAILABLE, a busy seller: seconds until it is worth trying again. */
+    retry_after_s?: number;
     [key: string]: unknown;
 }
 export declare class AmbasadaError extends Error {
@@ -76,6 +80,8 @@ export declare class AmbasadaError extends Error {
     get callId(): string | undefined;
     get refunded(): boolean;
     get approvalId(): string | undefined;
+    /** Seconds until it is worth trying again (CAP_TOOLS_RATE, TOOL_UNAVAILABLE, a busy seller), when the error says. */
+    get retryAfterS(): number | undefined;
     /** The wire shape, e.g. to pass an error on from your own endpoint. */
     toJSON(): {
         error: {
@@ -83,7 +89,7 @@ export declare class AmbasadaError extends Error {
             message: string;
         } & ErrorDetails;
     };
-    /** A `Response` with the wire shape and status (402 for receipt problems). */
+    /** A `Response` with the wire shape and status (402 for receipt problems), and `Retry-After` when it has one. */
     toResponse(): Response;
 }
 export type WebhookFailure = "missing_headers" | "bad_timestamp" | "too_old" | "too_new" | "bad_signature" | "bad_secret" | "bad_body";

package/dist/platform.d.ts

@@ -11,7 +11,7 @@ export { getHeader } from "./headers.js";
 export type { HeaderSource } from "./headers.js";
 export { defineApp } from "./define.js";
 export { MINIAPP_AGE_RATINGS, MINIAPP_ENTRY, MINIAPP_KINDS, supportUrl } from "./define.js";
-export type { AppConfig, MiniAppConfig } from "./define.js";
+export type { AppConfig, ListingConfig, MiniAppConfig } from "./define.js";
 export { AmbasadaAuth, AUTH_PATHS, JWKS_TTL_MS, SESSION_TTL_S } from "./auth.js";
 export type { AmbasadaUser, AuthConfig, LoginOptions, ShellUser, WithHeaders } from "./auth.js";
 export { AmbasadaApps, APP_SIGNATURE_HEADER, APP_TIMESTAMP_HEADER, appWebhookHeaders, signAppWebhook } from "./apps.js";

package/dist/platform.js

@@ -180,6 +180,8 @@ var ERROR_STATUS = {
   // SDK-side
   NETWORK: 0,
   CONFIG: 0,
+  /** A platform feature this app relies on is not switched on yet (silent sign-in before the hub has keys). */
+  NOT_CONFIGURED: 503,
   RECEIPT_INVALID: 402,
   WEBHOOK_INVALID: 400
 };
@@ -211,13 +213,19 @@ var AmbasadaError = class _AmbasadaError extends Error {
   get approvalId() {
     return this.details.approval_id;
   }
+  /** Seconds until it is worth trying again (CAP_TOOLS_RATE, TOOL_UNAVAILABLE, a busy seller), when the error says. */
+  get retryAfterS() {
+    const s = this.details.retry_after_s;
+    return typeof s === "number" && Number.isFinite(s) ? s : void 0;
+  }
   /** The wire shape, e.g. to pass an error on from your own endpoint. */
   toJSON() {
     return { error: { code: this.code, message: this.message, ...this.details } };
   }
-  /** A `Response` with the wire shape and status (402 for receipt problems). */
+  /** A `Response` with the wire shape and status (402 for receipt problems), and `Retry-After` when it has one. */
   toResponse() {
-    return Response.json(this.toJSON(), { status: this.status || 500 });
+    const retry = this.details.retry_after_s;
+    return Response.json(this.toJSON(), { status: this.status || 500, ...typeof retry === "number" ? { headers: { "retry-after": String(Math.ceil(retry)) } } : {} });
   }
 };
 var WebhookInvalidError = class extends AmbasadaError {
@@ -403,13 +411,17 @@ async function jwks(issuer, doFetch, refresh = false) {
   if (cached && !refresh && Date.now() - cached.at < JWKS_TTL_MS) return cached.keys;
   if (cached && refresh && Date.now() - cached.at < 6e4) return cached.keys;
   const res = await doFetch(`${issuer}/.well-known/jwks.json`, { headers: { accept: "application/json" } });
-  if (!res.ok) throw new AmbasadaError("UPSTREAM_ERROR", `could not read the Ambasada ID keys (${res.status})`, 502);
-  const body = await res.json();
+  if (res.status === 404) throw notConfigured(`${issuer} publishes no signing keys yet`);
+  if (!res.ok) throw new AmbasadaError("UPSTREAM_ERROR", `could not read the signing keys of ${issuer} (${res.status})`, 502);
+  const body = await res.json().catch(() => ({}));
   const keys3 = (body.keys ?? []).filter((k) => k.kty === "RSA" && k.n && k.e);
+  if (!keys3.length) throw notConfigured(`${issuer} publishes no RS256 signing keys yet`);
   jwksCache.set(issuer, { at: Date.now(), keys: keys3 });
   return keys3;
 }
+var hubOf = (c) => (c.hubUrl || DEFAULT_HUB_URL).replace(/\/+$/, "");
 var shellRefused = (message) => new AmbasadaError("UNAUTHORIZED", `shell token refused: ${message}`, 401);
+var notConfigured = (message) => new AmbasadaError("NOT_CONFIGURED", `silent sign-in is not configured: ${message}`, 503);
 var AmbasadaAuth = class {
   constructor(config) {
     this.config = config;
@@ -499,14 +511,15 @@ var AmbasadaAuth = class {
     return (await verifyCookie(secret, "session", readOurCookie(req, SESSION_COOKIE)))?.user ?? null;
   }
   /**
-   * Verifies a shell token (Clerk JWT template `ambasada-miniapp`, RS256, 60 s) against
-   * `<AMBASADA_AUTH_ISSUER>/.well-known/jwks.json` (cached 1 h): signature, expiry, issuer, and that its `aud`
-   * is this app (its id or origin). Returns who it is, or throws `AmbasadaError("UNAUTHORIZED")`.
+   * 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
+   * `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.
    */
   async verifyShellToken(token, options = {}) {
     const c = this.config();
-    if (!c.issuer) throw new AmbasadaError("CONFIG", "silent sign-in needs AMBASADA_AUTH_ISSUER (injected on ambasada.dev and by `ambasada dev`)");
-    const trusted = [c.issuer, c.hubUrl].filter((v) => !!v).map((v) => v.replace(/\/+$/, ""));
+    const trusted = [...new Set([c.issuer, hubOf(c)].filter((v) => !!v).map((v) => v.replace(/\/+$/, "")))];
     const audiences = [options.audience ?? c.audiences ?? []].flat().filter(Boolean).map((a) => a.replace(/\/+$/, ""));
     if (!audiences.length) throw new AmbasadaError("CONFIG", "silent sign-in needs to know this app: set AMBASADA_APP_ORIGIN or PUBLIC_URL, or pass { audience }");
     const doFetch = c.fetch ?? ((input, init) => fetch(input, init));
@@ -551,6 +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`)");
     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();
@@ -563,16 +577,13 @@ var AmbasadaAuth = class {
     const audiences = [...this.config().audiences ?? [], s.origin];
     const who = await this.verifyShellToken(token, { audience: audiences });
     let user = { id: who.user_id, name: who.name, avatar_url: who.avatar, builder: false, builder_since: null, member_since: null, pass: null };
-    const hub = this.config().hubUrl;
-    if (hub) {
-      try {
-        const res = await s.fetch(`${hub.replace(/\/+$/, "")}/api/apps/profile`, { headers: { authorization: `Bearer ${token}`, accept: "application/json" } });
-        if (res.ok) {
-          const profile = await res.json();
-          if (profile.id === who.user_id) user = { ...user, ...profile, id: who.user_id };
-        } else await res.body?.cancel();
-      } catch {
-      }
+    try {
+      const res = await s.fetch(`${hubOf(this.config())}/api/apps/profile`, { headers: { authorization: `Bearer ${token}`, accept: "application/json" } });
+      if (res.ok) {
+        const profile = await res.json();
+        if (profile.id === who.user_id) user = { ...user, ...profile, id: who.user_id };
+      } else await res.body?.cancel();
+    } catch {
     }
     const exp = Math.floor(Date.now() / 1e3) + SESSION_TTL_S;
     const session = await signCookie(s.clientSecret, "session", { user, exp });
@@ -592,6 +603,7 @@ var AmbasadaAuth = class {
 
 // src/client.ts
 var DEFAULT_API_URL = "https://api.ambasada.dev";
+var originOf = (url) => url && URL.canParse(url) ? new URL(url).origin : void 0;
 var isBinding = (v) => typeof v === "object" && v !== null && typeof v.fetch === "function";
 function processEnv() {
   const p = globalThis.process;
@@ -642,14 +654,13 @@ var Ambasada = class {
     issuer: this.options.auth?.issuer ?? this.env("AMBASADA_AUTH_ISSUER"),
     publicUrl: this.options.auth?.publicUrl ?? this.env("PUBLIC_URL"),
     apiUrl: this.apiUrl,
-    // Silent sign-in: a shell token must be for this app, by id or origin.
-    audiences: [this.appOrigin, this.options.app?.id ?? this.env("AMBASADA_APP_ID") ?? this.env("AMBASADA_COMPANY")].filter((a) => !!a),
+    // Silent sign-in: a shell token must be for this app, by origin (the deploy's and PUBLIC_URL) or id.
+    audiences: [...new Set([this.appOrigin, originOf(this.env("PUBLIC_URL")), this.options.app?.id, this.env("AMBASADA_APP_ID"), this.env("AMBASADA_COMPANY")].filter((a) => !!a))],
     hubUrl: this.hubUrl,
     fetch: this.fetcher
   }));
   get appOrigin() {
-    const url = this.options.app?.origin ?? this.env("AMBASADA_APP_ORIGIN") ?? this.options.auth?.publicUrl ?? this.env("PUBLIC_URL");
-    return url && URL.canParse(url) ? new URL(url).origin : void 0;
+    return originOf(this.options.app?.origin ?? this.env("AMBASADA_APP_ORIGIN") ?? this.options.auth?.publicUrl ?? this.env("PUBLIC_URL"));
   }
   get hubUrl() {
     return this.options.app?.hubUrl ?? this.env("AMBASADA_HUB_URL");
@@ -817,6 +828,11 @@ function supportUrl(value) {
   return void 0;
 }
 var MINIAPP_ENTRY = /^\/(?:[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*)?$/;
+function checkListing(id, key, l) {
+  if (l.age_rating !== void 0 && !MINIAPP_AGE_RATINGS.includes(l.age_rating)) throw new Error(`${id}: ${key}.age_rating must be one of ${MINIAPP_AGE_RATINGS.join(", ")} (got ${JSON.stringify(l.age_rating)})`);
+  if (l.kind !== void 0 && !MINIAPP_KINDS.includes(l.kind)) throw new Error(`${id}: ${key}.kind must be one of ${MINIAPP_KINDS.join(", ")} (got ${JSON.stringify(l.kind)})`);
+  if (l.tags !== void 0 && (!Array.isArray(l.tags) || l.tags.length > 5 || l.tags.some((t) => typeof t !== "string"))) throw new Error(`${id}: ${key}.tags must be up to 5 strings`);
+}
 function defineApp(config) {
   if (typeof config.id !== "string" || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(config.id)) throw new Error(`app id "${String(config.id)}" must be a lowercase slug (a-z, 0-9, -)`);
   const m = config.miniapp;
@@ -827,10 +843,12 @@ function defineApp(config) {
     }
     if (m.icon !== void 0 && (typeof m.icon !== "string" || !m.icon.startsWith("/"))) throw new Error(`${config.id}: miniapp.icon must be a path like "/icon.png"`);
     if (m.accent !== void 0 && !/^#[0-9a-fA-F]{6}$/.test(m.accent)) throw new Error(`${config.id}: miniapp.accent must be a #RRGGBB colour`);
-    if (m.age_rating !== void 0 && !MINIAPP_AGE_RATINGS.includes(m.age_rating)) throw new Error(`${config.id}: miniapp.age_rating must be one of ${MINIAPP_AGE_RATINGS.join(", ")} (got ${JSON.stringify(m.age_rating)})`);
-    if (m.kind !== void 0 && !MINIAPP_KINDS.includes(m.kind)) throw new Error(`${config.id}: miniapp.kind must be one of ${MINIAPP_KINDS.join(", ")} (got ${JSON.stringify(m.kind)})`);
+    checkListing(config.id, "miniapp", m);
     if (m.support !== void 0 && !supportUrl(m.support)) throw new Error(`${config.id}: miniapp.support must be an email or an https URL (got ${JSON.stringify(m.support)})`);
-    if (m.tags !== void 0 && (!Array.isArray(m.tags) || m.tags.length > 5 || m.tags.some((t) => typeof t !== "string"))) throw new Error(`${config.id}: miniapp.tags must be up to 5 strings`);
+  }
+  if (config.listing !== void 0) {
+    if (!config.listing || typeof config.listing !== "object") throw new Error(`${config.id}: listing must be { age_rating, kind, tags }`);
+    checkListing(config.id, "listing", config.listing);
   }
   if (config.support !== void 0 && !supportUrl(config.support)) throw new Error(`${config.id}: support must be an email or an https URL (got ${JSON.stringify(config.support)})`);
   return config;

package/package.json

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