@ambasada/sdk 0.8.2 → 0.8.3

package/dist/define.d.ts

@@ -2,18 +2,39 @@
  * `ambasada.config.ts` (docs/PLATFORM.md §3). Types and checks only; the CLI reads the values
  * (`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`
+ * 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.
+ */
+export interface MiniAppConfig {
+    /** 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;
+    /** Manifest fields beyond the defaults (docs/MINI-APPS.md §2). */
+    category?: "shopping" | "food" | "events" | "tools" | "learning" | "community" | "games" | "finance" | "other";
+    accent?: string;
+    /** What the app asks the shell for (default: identity and notifications, which the templates' routes serve). */
+    scopes?: ("identity" | "notifications")[];
+    visibility?: "public" | "builders" | "unlisted" | `event:${string}`;
+}
 export interface AppConfig {
     /** The app's slug (lowercase): it lives at https://<id>.ambasada.dev. */
     id: string;
     /** Display name. */
     name: string;
-    /** One line about the app: the manifest's subtitle and description (`ambasada init` writes them from it). */
+    /** One line about the app (the mini app's subtitle and description, when there is one). */
     description?: string;
     /** Where the app runs; `ambasada link` sets it when you host elsewhere. */
     product?: {
         url?: string;
     };
+    /** The mini app inside the Ambasada app, at a path of this one. Off without it. */
+    miniapp?: MiniAppConfig;
     /** Add-ons to load besides the ones found in node_modules (package names, e.g. "@ambasada/village"). */
     addons?: string[];
 }
+/** 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,8 @@ export type * from "./types.js";
 export { getHeader } from "./headers.js";
 export type { HeaderSource } from "./headers.js";
 export { defineApp } from "./define.js";
-export type { AppConfig } from "./define.js";
+export { MINIAPP_ENTRY } 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";
 export { AmbasadaApps, APP_SIGNATURE_HEADER, APP_TIMESTAMP_HEADER, appWebhookHeaders, signAppWebhook } from "./apps.js";

package/dist/platform.js

@@ -777,8 +777,18 @@ function getHeader(headers, name) {
 }
 
 // src/define.ts
+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, -)`);
+  const m = config.miniapp;
+  if (m !== void 0) {
+    if (!m || typeof m !== "object") throw new Error(`${config.id}: miniapp must be { entry: "/app" }`);
+    if (typeof m.entry !== "string" || !MINIAPP_ENTRY.test(m.entry) || m.entry.split("/").includes("..")) {
+      throw new Error(`${config.id}: miniapp.entry must be a path like "/app" or "/" (got ${JSON.stringify(m.entry)})`);
+    }
+    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`);
+  }
   return config;
 }
 
@@ -796,6 +806,7 @@ export {
   DEFAULT_API_URL,
   ERROR_STATUS,
   JWKS_TTL_MS,
+  MINIAPP_ENTRY,
   SESSION_TTL_S,
   WebhookInvalidError,
   ambasada,

package/package.json

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