@ambasada/sdk 0.8.9 → 0.8.11

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

@@ -40,9 +40,11 @@ export declare const ERROR_STATUS: {
     readonly APPROVALS_PENDING: 429;
     readonly PROVIDER_BUDGET: 503;
     readonly PROVIDER_DENIED: 502;
+    readonly TOOL_UNAVAILABLE: 503;
     readonly FROZEN: 403;
     readonly CAP_INBOX_RATE: 429;
     readonly CAP_CHAT_RATE: 429;
+    readonly CAP_TOOLS_RATE: 429;
     readonly NETWORK: 0;
     readonly CONFIG: 0;
     readonly RECEIPT_INVALID: 402;
@@ -61,6 +63,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 {
@@ -74,6 +78,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: {
@@ -81,7 +87,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

@@ -169,12 +169,14 @@ var ERROR_STATUS = {
   // LLMOK mapping (utilities stream, docs/LLMOK.md)
   PROVIDER_BUDGET: 503,
   PROVIDER_DENIED: 502,
+  TOOL_UNAVAILABLE: 503,
   // Clock windows (agent stream): deploys / steering refused while frozen
   FROZEN: 403,
   // Exchange stream: an agent sent too many inbox messages
   CAP_INBOX_RATE: 429,
   // The CEO chat: too many turns for one company
   CAP_CHAT_RATE: 429,
+  CAP_TOOLS_RATE: 429,
   // SDK-side
   NETWORK: 0,
   CONFIG: 0,
@@ -209,13 +211,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 {
@@ -815,6 +823,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;
@@ -825,10 +838,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.9",
+  "version": "0.8.11",
   "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.9"
+    "@ambasada/village": "^0.8.11"
   },
   "devDependencies": {
     "@types/node": "^22.20.5",