@greensecurity/javascript-sdk 0.46.0-beta.5 → 0.46.0-beta.7

package/dist/commonjs/apps/manifest.d.ts

@@ -0,0 +1,144 @@
+import * as z from "zod/v4";
+export { IPV4_OCTET_PATTERN, PORT_PATTERN, CSP_PATH_CHAR, CSP_SOURCE_MAX_CHARS, CSP_SOURCE_PATTERN, CSP_SOURCES_MAX_PER_DIRECTIVE, CSP_SOURCES_MAX_TOTAL_CHARS, cspSourcesTotalChars, HTTPS_URL_PATTERN, isHttpsUrl, isParsableHttpsUrl, } from "./url.js";
+/** A single SRI hash with the digest length its algorithm produces (32, 48 or 64 bytes, base64). */
+export declare const SRI_PATTERN = "^(sha256-[A-Za-z0-9+/]{43}=|sha384-[A-Za-z0-9+/]{64}|sha512-[A-Za-z0-9+/]{86}==)$";
+/** SemVer 2.0.0 (semver.org's reference pattern): no empty or leading-zero numeric identifiers. */
+export declare const SEMVER_PATTERN: string;
+export declare const COMPONENT_NAME_PATTERN = "^[A-Za-z_$][A-Za-z0-9_$]*$";
+/**
+ * A positive decimal integer no larger than `Number.MAX_SAFE_INTEGER` (9007199254740991), written
+ * as a string with no leading zeros: up to 15 digits freely, then 16-digit values digit by digit
+ * against the maximum. The server applies the same bound to a string `id`.
+ */
+export declare const SAFE_INTEGER_STRING_PATTERN: string;
+export declare const PERMISSION_PATTERN = "^[a-z0-9_-]+\\.[a-z0-9_-]+$";
+/**
+ * Permissions for platform features rather than Green Security data. An app lists them in
+ * `permissions` like any other, and they are granted with the app's role when it is installed.
+ * The server checks them against the app's role only, never against the viewer's role, so they
+ * never appear in a user token's data scope.
+ */
+export declare const PLATFORM_PERMISSIONS: readonly [{
+    readonly permission: "app_secrets.write";
+    readonly description: "Use the Secret Store: set, find, list and delete this app's secrets, with any token.";
+}];
+export type PlatformPermission = (typeof PLATFORM_PERMISSIONS)[number]["permission"];
+export declare function isPlatformPermission(value: unknown): value is PlatformPermission;
+/** Lifecycle events an app's own webhook endpoint can receive (see C19). */
+export declare const APP_WEBHOOK_EVENTS: readonly ["MarketplaceAppActivation.created", "MarketplaceAppActivation.updated", "MarketplaceAppActivation.destroyed"];
+export type AppWebhookEvent = (typeof APP_WEBHOOK_EVENTS)[number];
+/** The JSON Schema keeps the `pattern`; the parse check is TypeScript-side only. */
+export declare const httpsUrlSchema: z.ZodString;
+/** Rejects a CSP whose sources together would exceed {@link CSP_SOURCES_MAX_TOTAL_CHARS}. */
+export declare function addCspBudgetIssue(csp: {
+    connect_src?: readonly string[] | undefined;
+    image_src?: readonly string[] | undefined;
+} | undefined, ctx: z.RefinementCtx, path: ReadonlyArray<string | number>): void;
+/** Components may appear on many surfaces, but each surface takes exactly one view. */
+export declare function addDuplicateViewportIssues(views: ReadonlyArray<{
+    viewport: string;
+}> | undefined, ctx: z.RefinementCtx, path: ReadonlyArray<string | number>): void;
+export declare const cspSourceSchema: z.ZodString;
+export declare const appViewSchema: z.ZodObject<{
+    viewport: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    component: z.ZodString;
+}, z.core.$strict>;
+/** Constants are delivered to every view as `environment.constants`. */
+export declare const appConstantsSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+export declare const appCspSchema: z.ZodObject<{
+    connect_src: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    image_src: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    /** Accepted for manifests published before v2. Ignored: bundles run from a blob worker. */
+    script_src: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    purpose: z.ZodString;
+}, z.core.$strict>;
+export declare const appManifestSchema: z.ZodObject<{
+    id: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+    name: z.ZodString;
+    icon: z.ZodString;
+    short_description: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        permission: z.ZodString;
+        purpose: z.ZodString;
+        /**
+         * Why the app cannot work without a sensitive permission (see `isSensitivePermission` in
+         * `review.ts`). Required by the catalog review for a sensitive permission a submission
+         * adds; optional otherwise. Shown to Green Security reviewers and to installers.
+         */
+        justification: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    configuration_instructions: z.ZodString;
+    support_instructions: z.ZodString;
+    constants: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    ui_extensions: z.ZodOptional<z.ZodObject<{
+        bundle: z.ZodOptional<z.ZodObject<{
+            url: z.ZodString;
+            integrity: z.ZodString;
+        }, z.core.$strict>>;
+        views: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            viewport: z.ZodEnum<{
+                [x: string]: string;
+            }>;
+            component: z.ZodString;
+        }, z.core.$strict>>>;
+        /** Reserved for a future FullPageView. Stored and validated, not rendered. */
+        routes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            component: z.ZodString;
+        }, z.core.$strict>>>;
+        csp: z.ZodOptional<z.ZodObject<{
+            connect_src: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            image_src: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            /** Accepted for manifests published before v2. Ignored: bundles run from a blob worker. */
+            script_src: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            purpose: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    post_install_action: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<{
+            url: "url";
+            app_settings_view: "app_settings_view";
+            app_main_view: "app_main_view";
+        }>;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    webhooks: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        events: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            "MarketplaceAppActivation.created": "MarketplaceAppActivation.created";
+            "MarketplaceAppActivation.updated": "MarketplaceAppActivation.updated";
+            "MarketplaceAppActivation.destroyed": "MarketplaceAppActivation.destroyed";
+        }>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AppManifestV2 = z.infer<typeof appManifestSchema>;
+export type PostInstallAction = NonNullable<AppManifestV2["post_install_action"]>;
+/**
+ * What installing the app does when `post_install_action` is left out, so the server and the host
+ * never land an installer on a view the app does not have: nothing for a back-end-only app, the
+ * settings page for a settings-only app, and the app's main view otherwise. `null` means
+ * "no post-install step". An explicit action is returned unchanged.
+ */
+export declare function effectivePostInstallAction(manifest: Pick<AppManifestV2, "post_install_action" | "ui_extensions">): PostInstallAction | null;
+export type AppView = z.infer<typeof appViewSchema>;
+export type AppConstants = z.infer<typeof appConstantsSchema>;
+/**
+ * JSON Schema for the manifest, written to `shared/app-platform/manifest.schema.json` so the
+ * server can validate without TypeScript. The cross-field rules in `superRefine` are not in it.
+ */
+export declare function manifestJsonSchema(): Record<string, unknown>;
+export type ManifestValidation = {
+    ok: true;
+    manifest: AppManifestV2;
+} | {
+    ok: false;
+    issues: Array<{
+        path: string;
+        message: string;
+    }>;
+};
+export declare function validateManifest(input: unknown): ManifestValidation;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/commonjs/apps/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/apps/manifest.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/apps/manifest.js

@@ -0,0 +1,309 @@
+"use strict";
+/*
+ * Hand-written (not generated by Speakeasy). Part of the third-party app platform contract;
+ * see docs/third-party-apps/plan.md.
+ *
+ * The manifest a marketplace app publishes through `POST /api/marketplace/catalog`. Field names
+ * are snake_case because that is what the server stores. Constraints are written as `pattern`s
+ * and `enum`s wherever possible so `manifestJsonSchema` carries them to the server and the CLI
+ * too; the few that JSON Schema cannot express live in `superRefine` and are repeated by the
+ * server's own validation.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appManifestSchema = exports.appCspSchema = exports.appConstantsSchema = exports.appViewSchema = exports.cspSourceSchema = exports.httpsUrlSchema = exports.APP_WEBHOOK_EVENTS = exports.PLATFORM_PERMISSIONS = exports.PERMISSION_PATTERN = exports.SAFE_INTEGER_STRING_PATTERN = exports.COMPONENT_NAME_PATTERN = exports.SEMVER_PATTERN = exports.SRI_PATTERN = exports.isParsableHttpsUrl = exports.isHttpsUrl = exports.HTTPS_URL_PATTERN = exports.cspSourcesTotalChars = exports.CSP_SOURCES_MAX_TOTAL_CHARS = exports.CSP_SOURCES_MAX_PER_DIRECTIVE = exports.CSP_SOURCE_PATTERN = exports.CSP_SOURCE_MAX_CHARS = exports.CSP_PATH_CHAR = exports.PORT_PATTERN = exports.IPV4_OCTET_PATTERN = void 0;
+exports.isPlatformPermission = isPlatformPermission;
+exports.addCspBudgetIssue = addCspBudgetIssue;
+exports.addDuplicateViewportIssues = addDuplicateViewportIssues;
+exports.effectivePostInstallAction = effectivePostInstallAction;
+exports.manifestJsonSchema = manifestJsonSchema;
+exports.validateManifest = validateManifest;
+const z = __importStar(require("zod/v4"));
+const surfaces_js_1 = require("./surfaces.js");
+const url_js_1 = require("./url.js");
+// The URL and CSP-source rules live in the zod-free `url.ts` so the host renderer can use them
+// without bundling zod; re-exported here because they are part of the manifest contract.
+var url_js_2 = require("./url.js");
+Object.defineProperty(exports, "IPV4_OCTET_PATTERN", { enumerable: true, get: function () { return url_js_2.IPV4_OCTET_PATTERN; } });
+Object.defineProperty(exports, "PORT_PATTERN", { enumerable: true, get: function () { return url_js_2.PORT_PATTERN; } });
+Object.defineProperty(exports, "CSP_PATH_CHAR", { enumerable: true, get: function () { return url_js_2.CSP_PATH_CHAR; } });
+Object.defineProperty(exports, "CSP_SOURCE_MAX_CHARS", { enumerable: true, get: function () { return url_js_2.CSP_SOURCE_MAX_CHARS; } });
+Object.defineProperty(exports, "CSP_SOURCE_PATTERN", { enumerable: true, get: function () { return url_js_2.CSP_SOURCE_PATTERN; } });
+Object.defineProperty(exports, "CSP_SOURCES_MAX_PER_DIRECTIVE", { enumerable: true, get: function () { return url_js_2.CSP_SOURCES_MAX_PER_DIRECTIVE; } });
+Object.defineProperty(exports, "CSP_SOURCES_MAX_TOTAL_CHARS", { enumerable: true, get: function () { return url_js_2.CSP_SOURCES_MAX_TOTAL_CHARS; } });
+Object.defineProperty(exports, "cspSourcesTotalChars", { enumerable: true, get: function () { return url_js_2.cspSourcesTotalChars; } });
+Object.defineProperty(exports, "HTTPS_URL_PATTERN", { enumerable: true, get: function () { return url_js_2.HTTPS_URL_PATTERN; } });
+Object.defineProperty(exports, "isHttpsUrl", { enumerable: true, get: function () { return url_js_2.isHttpsUrl; } });
+Object.defineProperty(exports, "isParsableHttpsUrl", { enumerable: true, get: function () { return url_js_2.isParsableHttpsUrl; } });
+/** A single SRI hash with the digest length its algorithm produces (32, 48 or 64 bytes, base64). */
+exports.SRI_PATTERN = "^(sha256-[A-Za-z0-9+/]{43}=|sha384-[A-Za-z0-9+/]{64}|sha512-[A-Za-z0-9+/]{86}==)$";
+/** SemVer 2.0.0 (semver.org's reference pattern): no empty or leading-zero numeric identifiers. */
+exports.SEMVER_PATTERN = "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)" +
+    "(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?" +
+    "(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$";
+exports.COMPONENT_NAME_PATTERN = "^[A-Za-z_$][A-Za-z0-9_$]*$";
+/**
+ * A positive decimal integer no larger than `Number.MAX_SAFE_INTEGER` (9007199254740991), written
+ * as a string with no leading zeros: up to 15 digits freely, then 16-digit values digit by digit
+ * against the maximum. The server applies the same bound to a string `id`.
+ */
+exports.SAFE_INTEGER_STRING_PATTERN = "^(?:[1-9][0-9]{0,14}|[1-8][0-9]{15}|900[0-6][0-9]{12}|90070[0-9]{11}|90071[0-8][0-9]{10}" +
+    "|900719[0-8][0-9]{9}|9007199[0-1][0-9]{8}|90071992[0-4][0-9]{7}|900719925[0-3][0-9]{6}" +
+    "|9007199254[0-6][0-9]{5}|90071992547[0-3][0-9]{4}|9007199254740[0-8][0-9]{2}" +
+    "|90071992547409[0-8][0-9]|9007199254740990|9007199254740991)$";
+exports.PERMISSION_PATTERN = "^[a-z0-9_-]+\\.[a-z0-9_-]+$";
+/**
+ * Permissions for platform features rather than Green Security data. An app lists them in
+ * `permissions` like any other, and they are granted with the app's role when it is installed.
+ * The server checks them against the app's role only, never against the viewer's role, so they
+ * never appear in a user token's data scope.
+ */
+exports.PLATFORM_PERMISSIONS = Object.freeze([
+    {
+        permission: "app_secrets.write",
+        description: "Use the Secret Store: set, find, list and delete this app's secrets, with any token.",
+    },
+]);
+const PLATFORM_PERMISSION_NAMES = new Set(exports.PLATFORM_PERMISSIONS.map((p) => p.permission));
+function isPlatformPermission(value) {
+    return typeof value === "string" && PLATFORM_PERMISSION_NAMES.has(value);
+}
+const SURFACE_IDS = surfaces_js_1.SURFACES.map((s) => s.id);
+/** Lifecycle events an app's own webhook endpoint can receive (see C19). */
+exports.APP_WEBHOOK_EVENTS = [
+    "MarketplaceAppActivation.created",
+    "MarketplaceAppActivation.updated",
+    "MarketplaceAppActivation.destroyed",
+];
+/** Whether an https URL names a DNS host: its last label starts with a letter, so it is no IP literal. */
+function hasNamedHost(value) {
+    try {
+        const labels = new URL(value).hostname.split(".");
+        return /^[a-z]/i.test(labels[labels.length - 1] ?? "");
+    }
+    catch {
+        return false;
+    }
+}
+/** The JSON Schema keeps the `pattern`; the parse check is TypeScript-side only. */
+exports.httpsUrlSchema = z
+    .string()
+    .max(2048)
+    .regex(new RegExp(url_js_1.HTTPS_URL_PATTERN))
+    .refine(url_js_1.isParsableHttpsUrl, { message: "must be a valid https URL" });
+/** Rejects a CSP whose sources together would exceed {@link CSP_SOURCES_MAX_TOTAL_CHARS}. */
+function addCspBudgetIssue(csp, ctx, path) {
+    const total = (0, url_js_1.cspSourcesTotalChars)(csp);
+    if (total > url_js_1.CSP_SOURCES_MAX_TOTAL_CHARS) {
+        ctx.addIssue({
+            code: "custom",
+            path: [...path],
+            message: `connect_src and image_src together use ${total} characters; the limit is ${url_js_1.CSP_SOURCES_MAX_TOTAL_CHARS}`,
+        });
+    }
+}
+/** Components may appear on many surfaces, but each surface takes exactly one view. */
+function addDuplicateViewportIssues(views, ctx, path) {
+    const seen = new Set();
+    views?.forEach((view, i) => {
+        if (seen.has(view.viewport)) {
+            ctx.addIssue({
+                code: "custom",
+                path: [...path, i, "viewport"],
+                message: `duplicate viewport ${view.viewport}; each surface takes one view`,
+            });
+        }
+        seen.add(view.viewport);
+    });
+}
+exports.cspSourceSchema = z.string().max(url_js_1.CSP_SOURCE_MAX_CHARS).regex(new RegExp(url_js_1.CSP_SOURCE_PATTERN));
+exports.appViewSchema = z.strictObject({
+    viewport: z.enum(SURFACE_IDS),
+    component: z.string().max(100).regex(new RegExp(exports.COMPONENT_NAME_PATTERN)),
+});
+/** Constants are delivered to every view as `environment.constants`. */
+exports.appConstantsSchema = z.record(z.string().max(100).regex(/^[A-Za-z_][A-Za-z0-9_]*$/), z.union([z.string().max(2048), z.number(), z.boolean()]));
+exports.appCspSchema = z.strictObject({
+    connect_src: z.array(exports.cspSourceSchema).max(url_js_1.CSP_SOURCES_MAX_PER_DIRECTIVE).optional(),
+    image_src: z.array(exports.cspSourceSchema).max(url_js_1.CSP_SOURCES_MAX_PER_DIRECTIVE).optional(),
+    /** Accepted for manifests published before v2. Ignored: bundles run from a blob worker. */
+    script_src: z.array(z.string().max(2048)).max(50).optional(),
+    purpose: z.string().min(1).max(1000),
+});
+exports.appManifestSchema = z
+    .strictObject({
+    id: z.union([z.number().int().positive(), z.string().regex(new RegExp(exports.SAFE_INTEGER_STRING_PATTERN))]),
+    name: z.string().min(1).max(100),
+    icon: exports.httpsUrlSchema,
+    short_description: z.string().min(1).max(500),
+    version: z.string().max(64).regex(new RegExp(exports.SEMVER_PATTERN)).optional(),
+    permissions: z
+        .array(z.strictObject({
+        permission: z.string().max(100).regex(new RegExp(exports.PERMISSION_PATTERN)),
+        purpose: z.string().min(1).max(1000),
+        /**
+         * Why the app cannot work without a sensitive permission (see `isSensitivePermission` in
+         * `review.ts`). Required by the catalog review for a sensitive permission a submission
+         * adds; optional otherwise. Shown to Green Security reviewers and to installers.
+         */
+        justification: z.string().min(1).max(1000).optional(),
+    }))
+        .max(100)
+        .optional(),
+    configuration_instructions: z.string().min(1).max(20000),
+    support_instructions: z.string().min(1).max(20000),
+    constants: exports.appConstantsSchema.optional(),
+    ui_extensions: z
+        .strictObject({
+        bundle: z.strictObject({
+            url: exports.httpsUrlSchema,
+            integrity: z.string().max(200).regex(new RegExp(exports.SRI_PATTERN)),
+        }).optional(),
+        views: z.array(exports.appViewSchema).max(200).optional(),
+        /** Reserved for a future FullPageView. Stored and validated, not rendered. */
+        routes: z
+            .array(z.strictObject({
+            path: z.string().max(200).regex(/^\/[a-z0-9\-/:]*$/),
+            component: z.string().max(100).regex(new RegExp(exports.COMPONENT_NAME_PATTERN)),
+        }))
+            .max(50)
+            .optional(),
+        csp: exports.appCspSchema.optional(),
+    })
+        .optional(),
+    post_install_action: z
+        .strictObject({
+        type: z.enum(["url", "app_settings_view", "app_main_view"]),
+        url: exports.httpsUrlSchema.optional(),
+    })
+        .optional(),
+    // The app's own webhook endpoint: registered by the catalog when the manifest is published, not
+    // tied to any tenant, and sent only this app's lifecycle events. It is how a back-end-only app
+    // hears about its first install. `events` defaults to all of them.
+    webhooks: z
+        .strictObject({
+        url: exports.httpsUrlSchema.refine(hasNamedHost, { message: "must use a DNS host name, not an IP address" }),
+        events: z.array(z.enum(exports.APP_WEBHOOK_EVENTS)).min(1).max(exports.APP_WEBHOOK_EVENTS.length).optional(),
+    })
+        .optional(),
+})
+    .superRefine((manifest, ctx) => {
+    addDuplicateViewportIssues(manifest.ui_extensions?.views, ctx, ["ui_extensions", "views"]);
+    addCspBudgetIssue(manifest.ui_extensions?.csp, ctx, ["ui_extensions", "csp"]);
+    const events = manifest.webhooks?.events ?? [];
+    if (new Set(events).size !== events.length) {
+        ctx.addIssue({ code: "custom", path: ["webhooks", "events"], message: "events must not repeat" });
+    }
+    if (manifest.ui_extensions?.views?.length && !manifest.ui_extensions.bundle) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["ui_extensions", "bundle"],
+            message: "bundle is required when views are declared",
+        });
+    }
+    // `version` stays optional only for legacy (v1) manifests. Anything the host renders needs one:
+    // it names the runtime URL and reaches views as `ExtensionContext.app.version`.
+    if ((manifest.ui_extensions?.bundle || manifest.ui_extensions?.views?.length) && !manifest.version) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["version"],
+            message: "version is required when ui_extensions declares a bundle or views",
+        });
+    }
+    if (manifest.post_install_action?.type === "url" && !manifest.post_install_action.url) {
+        ctx.addIssue({ code: "custom", path: ["post_install_action", "url"], message: "url is required for type=url" });
+    }
+    // A back-end-only app has no views, so it cannot land installers on one. Checked only for
+    // versioned (v2) manifests: v1 apps may carry a post-install view type from before views existed.
+    const viewports = new Set((manifest.ui_extensions?.views ?? []).map((v) => v.viewport));
+    const versioned = manifest.version !== undefined;
+    if (versioned && manifest.post_install_action?.type === "app_settings_view" && !viewports.has("settings")) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["post_install_action", "type"],
+            message: "app_settings_view requires a view for the settings viewport",
+        });
+    }
+    // The settings page is not a main view: a settings-only app should land on app_settings_view.
+    const mainViewports = [...viewports].filter((v) => v !== "settings");
+    if (versioned && manifest.post_install_action?.type === "app_main_view" && mainViewports.length === 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["post_install_action", "type"],
+            message: "app_main_view requires a view other than settings",
+        });
+    }
+});
+/**
+ * What installing the app does when `post_install_action` is left out, so the server and the host
+ * never land an installer on a view the app does not have: nothing for a back-end-only app, the
+ * settings page for a settings-only app, and the app's main view otherwise. `null` means
+ * "no post-install step". An explicit action is returned unchanged.
+ */
+function effectivePostInstallAction(manifest) {
+    if (manifest.post_install_action)
+        return manifest.post_install_action;
+    const viewports = (manifest.ui_extensions?.views ?? []).map((v) => v.viewport);
+    if (viewports.some((v) => v !== "settings"))
+        return { type: "app_main_view" };
+    if (viewports.includes("settings"))
+        return { type: "app_settings_view" };
+    return null;
+}
+/**
+ * JSON Schema for the manifest, written to `shared/app-platform/manifest.schema.json` so the
+ * server can validate without TypeScript. The cross-field rules in `superRefine` are not in it.
+ */
+function manifestJsonSchema() {
+    return z.toJSONSchema(exports.appManifestSchema, {
+        target: "draft-2020-12",
+        // zod labels every `.regex()` string `format: "regex"`, which in JSON Schema means "this value
+        // is itself a regular expression". The `pattern` it emits alongside is the real constraint.
+        override: (ctx) => {
+            if (ctx.jsonSchema["format"] === "regex")
+                delete ctx.jsonSchema["format"];
+        },
+    });
+}
+function validateManifest(input) {
+    const result = exports.appManifestSchema.safeParse(input);
+    if (result.success)
+        return { ok: true, manifest: result.data };
+    return {
+        ok: false,
+        issues: result.error.issues.map((issue) => ({ path: issue.path.join("."), message: issue.message })),
+    };
+}
+//# sourceMappingURL=manifest.js.map

package/dist/commonjs/apps/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../../src/apps/manifest.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoEH,oDAEC;AA8BD,8CAaC;AAGD,gEAgBC;AA8ID,gEASC;AAQD,gDASC;AAMD,4CAQC;AAxTD,0CAA4B;AAC5B,+CAAyC;AACzC,qCAQkB;AAElB,+FAA+F;AAC/F,yFAAyF;AACzF,mCAYkB;AAXhB,4GAAA,kBAAkB,OAAA;AAClB,sGAAA,YAAY,OAAA;AACZ,uGAAA,aAAa,OAAA;AACb,8GAAA,oBAAoB,OAAA;AACpB,4GAAA,kBAAkB,OAAA;AAClB,uHAAA,6BAA6B,OAAA;AAC7B,qHAAA,2BAA2B,OAAA;AAC3B,8GAAA,oBAAoB,OAAA;AACpB,2GAAA,iBAAiB,OAAA;AACjB,oGAAA,UAAU,OAAA;AACV,4GAAA,kBAAkB,OAAA;AAIpB,oGAAoG;AACvF,QAAA,WAAW,GAAG,mFAAmF,CAAC;AAC/G,mGAAmG;AACtF,QAAA,cAAc,GACzB,gDAAgD;IAChD,sGAAsG;IACtG,+CAA+C,CAAC;AACrC,QAAA,sBAAsB,GAAG,4BAA4B,CAAC;AACnE;;;;GAIG;AACU,QAAA,2BAA2B,GACtC,0FAA0F;IAC1F,wFAAwF;IACxF,8EAA8E;IAC9E,+DAA+D,CAAC;AACrD,QAAA,kBAAkB,GAAG,6BAA6B,CAAC;AAEhE;;;;;GAKG;AACU,QAAA,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC;IAChD;QACE,UAAU,EAAE,mBAAmB;QAC/B,WAAW,EAAE,sFAAsF;KACpG;CACO,CAAC,CAAC;AAIZ,MAAM,yBAAyB,GAAwB,IAAI,GAAG,CAAC,4BAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;AAE9G,SAAgB,oBAAoB,CAAC,KAAc;IACjD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,yBAAyB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAC3E,CAAC;AACD,MAAM,WAAW,GAAG,sBAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAA0B,CAAC;AAEvE,4EAA4E;AAC/D,QAAA,kBAAkB,GAAG;IAChC,kCAAkC;IAClC,kCAAkC;IAClC,oCAAoC;CAC5B,CAAC;AAIX,0GAA0G;AAC1G,SAAS,YAAY,CAAC,KAAa;IACjC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAClD,OAAO,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,oFAAoF;AACvE,QAAA,cAAc,GAAG,CAAC;KAC5B,MAAM,EAAE;KACR,GAAG,CAAC,IAAI,CAAC;KACT,KAAK,CAAC,IAAI,MAAM,CAAC,0BAAiB,CAAC,CAAC;KACpC,MAAM,CAAC,2BAAkB,EAAE,EAAE,OAAO,EAAE,2BAA2B,EAAE,CAAC,CAAC;AAExE,6FAA6F;AAC7F,SAAgB,iBAAiB,CAC/B,GAA2G,EAC3G,GAAoB,EACpB,IAAoC;IAEpC,MAAM,KAAK,GAAG,IAAA,6BAAoB,EAAC,GAAG,CAAC,CAAC;IACxC,IAAI,KAAK,GAAG,oCAA2B,EAAE,CAAC;QACxC,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;YACf,OAAO,EAAE,0CAA0C,KAAK,6BAA6B,oCAA2B,EAAE;SACnH,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,uFAAuF;AACvF,SAAgB,0BAA0B,CACxC,KAAsD,EACtD,GAAoB,EACpB,IAAoC;IAEpC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5B,GAAG,CAAC,QAAQ,CAAC;gBACX,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,UAAU,CAAC;gBAC9B,OAAO,EAAE,sBAAsB,IAAI,CAAC,QAAQ,+BAA+B;aAC5E,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC;AAEY,QAAA,eAAe,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,6BAAoB,CAAC,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,2BAAkB,CAAC,CAAC,CAAC;AAE7F,QAAA,aAAa,GAAG,CAAC,CAAC,YAAY,CAAC;IAC1C,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC;IAC7B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,8BAAsB,CAAC,CAAC;CACzE,CAAC,CAAC;AAEH,wEAAwE;AAC3D,QAAA,kBAAkB,GAAG,CAAC,CAAC,MAAM,CACxC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC,EACrD,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CACzD,CAAC;AAEW,QAAA,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC;IACzC,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,uBAAe,CAAC,CAAC,GAAG,CAAC,sCAA6B,CAAC,CAAC,QAAQ,EAAE;IACnF,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,uBAAe,CAAC,CAAC,GAAG,CAAC,sCAA6B,CAAC,CAAC,QAAQ,EAAE;IACjF,2FAA2F;IAC3F,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC5D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;CACrC,CAAC,CAAC;AAEU,QAAA,iBAAiB,GAAG,CAAC;KAC/B,YAAY,CAAC;IACZ,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,mCAA2B,CAAC,CAAC,CAAC,CAAC;IACrG,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IAChC,IAAI,EAAE,sBAAc;IACpB,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IAC7C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,sBAAc,CAAC,CAAC,CAAC,QAAQ,EAAE;IACxE,WAAW,EAAE,CAAC;SACX,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC;QACpB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,0BAAkB,CAAC,CAAC;QACrE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;QACpC;;;;WAIG;QACH,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;KACtD,CAAC,CAAC;SACF,GAAG,CAAC,GAAG,CAAC;SACR,QAAQ,EAAE;IACb,0BAA0B,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;IACxD,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;IAClD,SAAS,EAAE,0BAAkB,CAAC,QAAQ,EAAE;IACxC,aAAa,EAAE,CAAC;SACb,YAAY,CAAC;QACZ,MAAM,EAAE,CAAC,CAAC,YAAY,CAAC;YACrB,GAAG,EAAE,sBAAc;YACnB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,mBAAW,CAAC,CAAC;SAC9D,CAAC,CAAC,QAAQ,EAAE;QACb,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,qBAAa,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;QACjD,8EAA8E;QAC9E,MAAM,EAAE,CAAC;aACN,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC;YACpB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC;YACpD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,8BAAsB,CAAC,CAAC;SACzE,CAAC,CAAC;aACF,GAAG,CAAC,EAAE,CAAC;aACP,QAAQ,EAAE;QACb,GAAG,EAAE,oBAAY,CAAC,QAAQ,EAAE;KAC7B,CAAC;SACD,QAAQ,EAAE;IACb,mBAAmB,EAAE,CAAC;SACnB,YAAY,CAAC;QACZ,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,mBAAmB,EAAE,eAAe,CAAC,CAAC;QAC3D,GAAG,EAAE,sBAAc,CAAC,QAAQ,EAAE;KAC/B,CAAC;SACD,QAAQ,EAAE;IACb,gGAAgG;IAChG,+FAA+F;IAC/F,mEAAmE;IACnE,QAAQ,EAAE,CAAC;SACR,YAAY,CAAC;QACZ,GAAG,EAAE,sBAAc,CAAC,MAAM,CAAC,YAAY,EAAE,EAAE,OAAO,EAAE,6CAA6C,EAAE,CAAC;QACpG,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,0BAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,0BAAkB,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE;KAC7F,CAAC;SACD,QAAQ,EAAE;CACd,CAAC;KACD,WAAW,CAAC,CAAC,QAAQ,EAAE,GAAG,EAAE,EAAE;IAC7B,0BAA0B,CAAC,QAAQ,CAAC,aAAa,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3F,iBAAiB,CAAC,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC,CAAC;IAC9E,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,CAAC;IAC/C,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;QAC3C,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,wBAAwB,EAAE,CAAC,CAAC;IACpG,CAAC;IAED,IAAI,QAAQ,CAAC,aAAa,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,MAAM,EAAE,CAAC;QAC5E,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,eAAe,EAAE,QAAQ,CAAC;YACjC,OAAO,EAAE,4CAA4C;SACtD,CAAC,CAAC;IACL,CAAC;IAED,gGAAgG;IAChG,gFAAgF;IAChF,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,IAAI,QAAQ,CAAC,aAAa,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QACnG,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,SAAS,CAAC;YACjB,OAAO,EAAE,mEAAmE;SAC7E,CAAC,CAAC;IACL,CAAC;IAED,IAAI,QAAQ,CAAC,mBAAmB,EAAE,IAAI,KAAK,KAAK,IAAI,CAAC,QAAQ,CAAC,mBAAmB,CAAC,GAAG,EAAE,CAAC;QACtF,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,qBAAqB,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,8BAA8B,EAAE,CAAC,CAAC;IAClH,CAAC;IAED,0FAA0F;IAC1F,kGAAkG;IAClG,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,aAAa,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxF,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,KAAK,SAAS,CAAC;IACjD,IAAI,SAAS,IAAI,QAAQ,CAAC,mBAAmB,EAAE,IAAI,KAAK,mBAAmB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;QAC1G,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,qBAAqB,EAAE,MAAM,CAAC;YACrC,OAAO,EAAE,6DAA6D;SACvE,CAAC,CAAC;IACL,CAAC;IACD,8FAA8F;IAC9F,MAAM,aAAa,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC;IACrE,IAAI,SAAS,IAAI,QAAQ,CAAC,mBAAmB,EAAE,IAAI,KAAK,eAAe,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtG,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,qBAAqB,EAAE,MAAM,CAAC;YACrC,OAAO,EAAE,mDAAmD;SAC7D,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC,CAAC;AAML;;;;;GAKG;AACH,SAAgB,0BAA0B,CACxC,QAAsE;IAEtE,IAAI,QAAQ,CAAC,mBAAmB;QAAE,OAAO,QAAQ,CAAC,mBAAmB,CAAC;IAEtE,MAAM,SAAS,GAAG,CAAC,QAAQ,CAAC,aAAa,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC/E,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,UAAU,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;IAC9E,IAAI,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,mBAAmB,EAAE,CAAC;IACzE,OAAO,IAAI,CAAC;AACd,CAAC;AAID;;;GAGG;AACH,SAAgB,kBAAkB;IAChC,OAAO,CAAC,CAAC,YAAY,CAAC,yBAAiB,EAAE;QACvC,MAAM,EAAE,eAAe;QACvB,+FAA+F;QAC/F,4FAA4F;QAC5F,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE;YAChB,IAAI,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,OAAO;gBAAE,OAAO,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAC5E,CAAC;KACF,CAA4B,CAAC;AAChC,CAAC;AAMD,SAAgB,gBAAgB,CAAC,KAAc;IAC7C,MAAM,MAAM,GAAG,yBAAiB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAClD,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;IAE/D,OAAO;QACL,EAAE,EAAE,KAAK;QACT,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;KACrG,CAAC;AACJ,CAAC"}

package/dist/commonjs/apps/protocol.d.ts

@@ -0,0 +1,116 @@
+import type { AppTokens, ExtensionContext } from "./context.js";
+import type { DevSessionDescriptor } from "./devsession.js";
+import type { RouteDescriptor } from "./route.js";
+import type { SurfaceId } from "./surfaces.js";
+/**
+ * Structural copy of `@remote-dom/core`'s `RemoteConnection`, so this contract does not pull the
+ * rendering libraries into every SDK consumer. Kept assignable both ways with the real type.
+ */
+export interface RemoteConnection {
+    mutate(records: readonly RemoteMutationRecord[]): void;
+    call(id: string, method: string, ...args: readonly unknown[]): unknown;
+}
+/** `@remote-dom/core` mutation records: insert child, remove child, update text, update property. */
+export type RemoteMutationRecord = readonly [type: 0, parentId: string, child: unknown, index: number] | readonly [type: 1, parentId: string, index: number] | readonly [type: 2, textId: string, text: string] | readonly [type: 3, id: string, name: string, value: unknown, updateType?: 1 | 2 | 3];
+export type ViewType = "context" | "focus" | "settings";
+/** Implemented inside the worker by the SDK runtime (`defineApp`). */
+export interface SandboxExports {
+    mount(args: {
+        mountId: string;
+        /** Exported component name from the manifest's `views[].component`. */
+        viewComponent: string;
+        surfaceId: SurfaceId;
+        connection: RemoteConnection;
+        context: ExtensionContext;
+        host: HostApi;
+    }): Promise<void>;
+    unmount(mountId: string): Promise<void>;
+    updateContext(mountId: string, patch: Partial<ExtensionContext>): Promise<void>;
+    ping(): Promise<"pong">;
+}
+export type ToastType = "success" | "caution" | "pending";
+/** Implemented by the host (web-mobile-client). Every method is async across the thread. */
+export interface HostApi {
+    refreshTokens(): Promise<AppTokens>;
+    navigate(to: RouteDescriptor): Promise<void>;
+    /** https only; the host asks the user to confirm. Resolves false when declined or rejected. */
+    openExternalUrl(url: string): Promise<boolean>;
+    /** `message` must be 1–30 characters. */
+    showToast(message: string, opts?: {
+        type?: ToastType;
+    }): Promise<void>;
+    /** Invalidates the host's cached data so its screens re-fetch after the app writes. */
+    refreshHostData(): Promise<void>;
+    clipboardWriteText(text: string): Promise<void>;
+    closeView(): Promise<void>;
+}
+export declare const TOAST_MAX_LENGTH = 30;
+/** Largest single envelope either side accepts, in UTF-16 code units of its JSON form. */
+export declare const MAX_ENVELOPE_CHARS = 1000000;
+export declare const HEARTBEAT_INTERVAL_MS = 2000;
+export declare const HEARTBEAT_MAX_MISSES = 3;
+interface InitBase {
+    kind: "init";
+    protocolVersion: ExtensionContext["protocolVersion"];
+    appId: number;
+}
+/**
+ * Exactly one code source: the published bundle (checked against its SRI hash), or a dev session
+ * (checked against signed build events) for the developer who owns an active `apps-cli dev`.
+ */
+export type BootstrapInit = (InitBase & {
+    bundle: {
+        url: string;
+        integrity: string;
+    };
+    devSession?: never;
+}) | (InitBase & {
+    devSession: DevSessionDescriptor;
+    bundle?: never;
+});
+export type HostToBootstrap = BootstrapInit | {
+    kind: "thread";
+    data: unknown;
+} | {
+    kind: "terminate";
+};
+export type BootstrapToHost = {
+    kind: "ready";
+} | {
+    kind: "thread";
+    data: unknown;
+}
+/** The bundle failed its integrity or signature check and was not executed. */
+ | {
+    kind: "integrity_failed";
+    reason: string;
+} | {
+    kind: "crashed";
+    reason: string;
+}
+/** Dev sessions only: a verified rebuild replaced the worker; the host remounts every view. */
+ | {
+    kind: "reloaded";
+    seq: number;
+} | {
+    kind: "log";
+    level: "debug" | "info" | "warn" | "error";
+    message: string;
+}
+/** Dev sessions only: build diagnostics from the CLI. */
+ | {
+    kind: "build_error";
+    diagnostics: Array<{
+        file?: string;
+        line?: number;
+        message: string;
+    }>;
+};
+/**
+ * Shape check for envelopes the host receives from the sandbox, which is untrusted: every
+ * variant's payload is checked, not just its `kind`. The payload of `thread` is checked by the
+ * thread layer.
+ */
+export declare function isBootstrapToHost(value: unknown): value is BootstrapToHost;
+export {};
+//# sourceMappingURL=protocol.d.ts.map

package/dist/commonjs/apps/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../src/apps/protocol.ts"],"names":[],"mappings":"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"}