@ambasada/sdk 0.8.4 → 0.8.6

package/dist/client.d.ts

@@ -15,7 +15,10 @@ export interface AmbasadaOptions {
     fetch?: typeof fetch;
     /** Per-request timeout in ms (default 45 s). */
     timeoutMs?: number;
-    /** Extra env source, e.g. a Worker's `env`. Default: `process.env` where it exists. */
+    /**
+     * Extra env source, e.g. a Worker's `env`. Default: `process.env` where it exists. A Worker hosted on ambasada.dev has
+     * 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`. */
     auth?: {
@@ -58,6 +61,11 @@ export declare class Ambasada {
     private projectPromise?;
     constructor(options?: AmbasadaOptions);
     protected env(name: string): string | undefined;
+    /**
+     * How this client fetches: `options.fetch`; else, with an `AMBASADA_API` service binding in `env` (hosted on
+     * ambasada.dev), the API's own URLs go through it and everything else (the hub, the issuer) through `fetch`.
+     */
+    protected get fetcher(): typeof fetch;
     get apiUrl(): string;
     protected get apiKey(): string;
     /**

package/dist/define.d.ts

@@ -12,6 +12,18 @@ export interface MiniAppConfig {
     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"). */
+    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;
+    /** Up to 5 search words. */
+    tags?: string[];
+    /** Under the name on the card (≤ 40; default: `description`, cut to one line). */
+    subtitle?: string;
+    /** The store description (≤ 170; default: the app's `description`). */
+    description?: string;
     /** Manifest fields beyond the defaults (docs/MINI-APPS.md §2). */
     category?: "shopping" | "food" | "events" | "tools" | "learning" | "community" | "games" | "finance" | "other";
     accent?: string;
@@ -26,6 +38,8 @@ export interface AppConfig {
     name: string;
     /** One line about the app (the mini app's subtitle and description, when there is one). */
     description?: string;
+    /** Where people get help: an email ("you@team.ro" or "mailto:…") or an https URL. The mini app's `support` by default. */
+    support?: string;
     /** Where the app runs; `ambasada link` sets it when you host elsewhere. */
     product?: {
         url?: string;
@@ -35,6 +49,10 @@ export interface AppConfig {
     /** Add-ons to load besides the ones found in node_modules (package names, e.g. "@ambasada/village"). */
     addons?: string[];
 }
+export declare const MINIAPP_AGE_RATINGS: readonly ["4+", "9+", "12+", "17+"];
+export declare const MINIAPP_KINDS: readonly ["product", "event", "tool", "assistant"];
+/** "you@team.ro" → "mailto:you@team.ro"; mailto: and https URLs as they are; anything else undefined. */
+export declare function supportUrl(value: string | undefined): string | undefined;
 /** A path the mini app may open at: absolute, no query, hash, `..` or `//`. */
 export declare const MINIAPP_ENTRY: RegExp;
 export declare function defineApp<T extends AppConfig>(config: T): T;

package/dist/platform.d.ts

@@ -10,7 +10,7 @@ export type * from "./types.js";
 export { getHeader } from "./headers.js";
 export type { HeaderSource } from "./headers.js";
 export { defineApp } from "./define.js";
-export { MINIAPP_ENTRY } from "./define.js";
+export { MINIAPP_AGE_RATINGS, MINIAPP_ENTRY, MINIAPP_KINDS, supportUrl } from "./define.js";
 export type { AppConfig, 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";

package/dist/platform.js

@@ -590,6 +590,7 @@ var AmbasadaAuth = class {
 
 // src/client.ts
 var DEFAULT_API_URL = "https://api.ambasada.dev";
+var isBinding = (v) => typeof v === "object" && v !== null && typeof v.fetch === "function";
 function processEnv() {
   const p = globalThis.process;
   return p?.env ?? {};
@@ -605,6 +606,22 @@ var Ambasada = class {
     const v = this.options.env?.[name];
     return typeof v === "string" ? v : processEnv()[name];
   }
+  /**
+   * How this client fetches: `options.fetch`; else, with an `AMBASADA_API` service binding in `env` (hosted on
+   * ambasada.dev), the API's own URLs go through it and everything else (the hub, the issuer) through `fetch`.
+   */
+  get fetcher() {
+    if (this.options.fetch) return this.options.fetch;
+    const binding = this.options.env?.AMBASADA_API;
+    if (!isBinding(binding)) return (input, init) => fetch(input, init);
+    const api = new Set(
+      [this.apiUrl, this.env("AMBASADA_API_URL"), this.env("AMBASADA_VILLAGE_API_URL")].filter((u) => !!u && URL.canParse(u)).map((u) => new URL(u).origin)
+    );
+    return (input, init) => {
+      const request = new Request(input, init);
+      return api.has(new URL(request.url).origin) ? binding.fetch(request) : fetch(request);
+    };
+  }
   get apiUrl() {
     return (this.options.apiUrl ?? this.env("AMBASADA_API_URL") ?? this.env("VILLAGE_API_URL") ?? DEFAULT_API_URL).replace(/\/+$/, "");
   }
@@ -626,7 +643,7 @@ var Ambasada = class {
     // 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),
     hubUrl: this.hubUrl,
-    fetch: this.options.fetch
+    fetch: this.fetcher
   }));
   get appOrigin() {
     const url = this.options.app?.origin ?? this.env("AMBASADA_APP_ORIGIN") ?? this.options.auth?.publicUrl ?? this.env("PUBLIC_URL");
@@ -643,7 +660,7 @@ var Ambasada = class {
     appSecret: this.options.app?.secret ?? this.env("AMBASADA_APP_SECRET"),
     hubUrl: this.hubUrl,
     origin: this.appOrigin,
-    fetch: this.options.fetch
+    fetch: this.fetcher
   }));
   // ── HTTP ──────────────────────────────────────────────────────────────────
   async send(method, path, opts = {}) {
@@ -657,7 +674,7 @@ var Ambasada = class {
       headers["content-type"] = "application/json";
     }
     for (const [k, v] of Object.entries(opts.headers ?? {})) if (v !== void 0) headers[k.toLowerCase()] = v;
-    const doFetch = this.options.fetch ?? fetch;
+    const doFetch = this.fetcher;
     const attempt = () => {
       const timeout = AbortSignal.timeout(this.options.timeoutMs ?? 45e3);
       const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
@@ -779,6 +796,15 @@ function getHeader(headers, name) {
 }
 
 // src/define.ts
+var MINIAPP_AGE_RATINGS = ["4+", "9+", "12+", "17+"];
+var MINIAPP_KINDS = ["product", "event", "tool", "assistant"];
+function supportUrl(value) {
+  const v = value?.trim();
+  if (!v) return void 0;
+  if (/^mailto:[^@\s]+@[^@\s]+$/.test(v) || /^https:\/\/\S+$/.test(v)) return v;
+  if (/^[^@\s:/]+@[^@\s]+\.[^@\s]+$/.test(v)) return `mailto:${v}`;
+  return void 0;
+}
 var MINIAPP_ENTRY = /^\/(?:[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*)?$/;
 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, -)`);
@@ -790,7 +816,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)})`);
+    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.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;
 }
 
@@ -808,7 +839,9 @@ export {
   DEFAULT_API_URL,
   ERROR_STATUS,
   JWKS_TTL_MS,
+  MINIAPP_AGE_RATINGS,
   MINIAPP_ENTRY,
+  MINIAPP_KINDS,
   SESSION_TTL_S,
   WebhookInvalidError,
   ambasada,
@@ -819,5 +852,6 @@ export {
   errorFromResponse,
   getHeader,
   isAmbasadaError,
-  signAppWebhook2 as signAppWebhook
+  signAppWebhook2 as signAppWebhook,
+  supportUrl
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ambasada/sdk",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "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.4"
+    "@ambasada/village": "^0.8.6"
   },
   "devDependencies": {
     "@types/node": "^22.20.5",