@proveanything/smartlinks 1.17.5 → 2.0.0-alpha.1

package/dist/openapi.yaml

@@ -38,6 +38,7 @@ tags:
   - name: crate
   - name: facets
   - name: form
+  - name: integrations
   - name: interactions
   - name: jobs
   - name: journeys
@@ -4164,6 +4165,33 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /admin/collection/{collectionId}/integrations/record-types:
+    get:
+      tags:
+        - integrations
+      summary: Discover the app-record types present in a collection + which app owns each (introspected), for picking a sub-record source/trigger.
+      operationId: integrations_listRecordTypes
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RecordTypesResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /admin/collection/{collectionId}/interactions:
     get:
       tags:
@@ -17215,6 +17243,109 @@ components:
       required:
         - files
         - function
+    AppFunctionTrigger:
+      type: object
+      properties:
+        type:
+          $ref: "#/components/schemas/AppFunctionTriggerType"
+        eventTypes:
+          type: array
+          items:
+            type: string
+        schedule:
+          type: string
+        route:
+          type: string
+        methods:
+          type: array
+          items:
+            type: string
+            enum:
+              - GET
+              - POST
+              - PUT
+              - PATCH
+              - DELETE
+      required:
+        - type
+    AppFunctionDef:
+      type: object
+      properties:
+        name:
+          type: string
+        description:
+          type: string
+        trigger:
+          $ref: "#/components/schemas/AppFunctionTrigger"
+        visibility:
+          $ref: "#/components/schemas/AppFunctionVisibility"
+        authority:
+          $ref: "#/components/schemas/AppFunctionAuthority"
+        elevated:
+          type: boolean
+        capabilities:
+          type: array
+          items:
+            type: string
+        apiVersion:
+          type: string
+        handler:
+          type: string
+      required:
+        - name
+        - trigger
+    AppManifestFunctions:
+      type: object
+      properties:
+        files:
+          $ref: "#/components/schemas/AppManifestFiles"
+        definitions:
+          type: array
+          items:
+            $ref: "#/components/schemas/AppFunctionDef"
+      required:
+        - files
+        - definitions
+    ServerFunctionCaller:
+      type: object
+      properties:
+        userId:
+          type: string
+        anonymous:
+          type: boolean
+        origin:
+          type: string
+        ip:
+          type: string
+        via:
+          $ref: "#/components/schemas/AppFunctionTriggerType"
+      required:
+        - userId
+        - anonymous
+        - via
+    ServerFunctionContext:
+      type: object
+      properties:
+        collectionId:
+          type: string
+        appId:
+          type: string
+        sl: {}
+        secrets:
+          type: object
+          additionalProperties: true
+        caller:
+          $ref: "#/components/schemas/ServerFunctionCaller"
+        fetch:
+          type: object
+          additionalProperties: true
+      required:
+        - collectionId
+        - appId
+        - sl
+        - secrets
+        - caller
+        - fetch
     AppAdminConfig:
       type: object
       properties:
@@ -17357,6 +17488,8 @@ components:
             $ref: "#/components/schemas/DeepLinkEntry"
         executor:
           $ref: "#/components/schemas/AppManifestExecutor"
+        functions:
+          $ref: "#/components/schemas/AppManifestFunctions"
       required:
         - name
         - version
@@ -17397,6 +17530,22 @@ components:
       properties:
         force:
           type: boolean
+    AppFunctionTriggerType:
+      type: string
+      enum:
+        - http
+        - event
+        - cron
+    AppFunctionVisibility:
+      type: string
+      enum:
+        - admin
+        - public
+    AppFunctionAuthority:
+      type: string
+      enum:
+        - caller
+        - collection
     PaginatedResponse:
       type: object
       properties:
@@ -23429,6 +23578,28 @@ components:
       properties:
         purpose:
           type: string
+    RecordTypeInfo:
+      type: object
+      properties:
+        appId:
+          type: string
+        recordType:
+          type: string
+        count:
+          type: number
+      required:
+        - appId
+        - recordType
+        - count
+    RecordTypesResponse:
+      type: object
+      properties:
+        recordTypes:
+          type: array
+          items:
+            $ref: "#/components/schemas/RecordTypeInfo"
+      required:
+        - recordTypes
     RunFlowResult:
       type: object
       additionalProperties: true

package/dist/testing/index.d.ts

@@ -0,0 +1,64 @@
+import type { AppFunctionDef, ServerFunctionContext } from '../types/appManifest';
+export declare class CapabilityError extends Error {
+    capability: string;
+    code: string;
+    constructor(capability: string, message?: string);
+}
+/** The surface `ctx.sl` exposes — mirrors the server facade. Provide the methods your test needs. */
+export interface TestSlImpl {
+    appRecords?: {
+        create?(fields: any): any;
+        update?(id: string, fields: any): any;
+        upsert?(fields: any): any;
+        delete?(id: string): any;
+        get?(id: string): any;
+        query?(params: any): any;
+        listTypes?(): any;
+    };
+    products?: {
+        get?(id: string, opts?: any): any;
+        query?(body?: any, opts?: any): any;
+        create?(data: any, opts?: any): any;
+        update?(id: string, data: any, opts?: any): any;
+    };
+    attestations?: {
+        create?(fields: any): any;
+    };
+}
+export interface TestCaller {
+    userId?: string | null;
+    anonymous?: boolean;
+    origin?: string | null;
+    ip?: string | null;
+}
+export interface CreateFunctionTestContextOptions {
+    /** The manifest declaration under test — its `capabilities` are the enforced envelope. */
+    def: Pick<AppFunctionDef, 'capabilities' | 'trigger' | 'visibility' | 'authority'>;
+    collectionId?: string;
+    appId?: string;
+    caller?: TestCaller;
+    /** Fixture secrets, keyed by ref. Real sealed secrets are server-only and never available locally. */
+    secrets?: Record<string, string>;
+    /** Backing impl for ctx.sl. Omit for pure unit tests (methods return a stub echo). */
+    sl?: TestSlImpl;
+    /** Backing fetch (defaults to global fetch). Still gated by the `network` capability. */
+    fetch?: typeof fetch;
+}
+export interface FunctionTestContext extends ServerFunctionContext {
+    /** Captured log lines (also written via ctx.log). */
+    logs: Array<{
+        at: string;
+        message: string;
+        data?: Record<string, any>;
+    }>;
+}
+/**
+ * Build a capability-enforcing test ctx for a server function. Run your handler with it:
+ *
+ *   const ctx = createFunctionTestContext({ def, caller: { userId: 'me' }, secrets: { k: 'v' } })
+ *   const result = await myHandler(ctx, { method: 'POST', body: { … } })
+ *
+ * A ctx.sl / ctx.secrets / ctx.fetch call not covered by `def.capabilities` throws
+ * CapabilityError — exactly as it would in production.
+ */
+export declare function createFunctionTestContext(opts: CreateFunctionTestContextOptions): FunctionTestContext;

package/dist/testing/index.js

@@ -0,0 +1,145 @@
+// src/testing/index.ts
+//
+// Local test harness for SmartLinks server functions — importable as
+// `@proveanything/smartlinks/testing`. It builds a `ctx` that matches the runtime
+// contract AND enforces the declared capability envelope, so a function fails locally
+// the same way it would after deploy — no "deploy and pray".
+//
+// Fidelity (documented in docs/server-functions.md "Testing & preview"):
+//  - Capabilities are enforced EXACTLY as declared in the manifest `def` — pass the def
+//    itself so "tested" can't drift from "declared".
+//  - `ctx.sl` delegates to an impl you inject: your live SDK for real reads/writes, or
+//    omit it for pure unit tests (methods return a stub result instead of hitting the
+//    network — control flow + capability enforcement still run).
+//  - `ctx.secrets` are FIXTURES you provide; real sealed secrets are server-only and
+//    never resolvable locally.
+//  - `ctx.fetch` is gated by the `network` capability just like production.
+export class CapabilityError extends Error {
+    constructor(capability, message) {
+        super(message || `capability not granted: ${capability}`);
+        this.code = 'CAPABILITY_DENIED';
+        this.name = 'CapabilityError';
+        this.capability = capability;
+    }
+}
+// The SAME grammar the server enforces (prove server/services/functions/validate.js).
+function parseCapabilities(list = []) {
+    const sl = new Set();
+    const secrets = new Set();
+    const networkHosts = new Set();
+    let networkAll = false;
+    for (const raw of list || []) {
+        const cap = String(raw || '').trim();
+        if (!cap)
+            continue;
+        if (cap === 'network') {
+            networkAll = true;
+            continue;
+        }
+        if (cap.startsWith('network:')) {
+            networkHosts.add(cap.slice(8).toLowerCase());
+            continue;
+        }
+        if (cap.startsWith('secrets:')) {
+            secrets.add(cap.slice(8));
+            continue;
+        }
+        if (cap.startsWith('sl:')) {
+            sl.add(cap.slice(3));
+            continue;
+        }
+    }
+    return { sl, secrets, networkAll, networkHosts };
+}
+function allowsSl(p, resource, op) {
+    if (p.sl.has(`${resource}:${op}`))
+        return true;
+    if (op === 'read' && p.sl.has(`${resource}:write`))
+        return true; // write implies read
+    return false;
+}
+const stub = (method, args) => ({ __stub: true, method, args });
+/**
+ * Build a capability-enforcing test ctx for a server function. Run your handler with it:
+ *
+ *   const ctx = createFunctionTestContext({ def, caller: { userId: 'me' }, secrets: { k: 'v' } })
+ *   const result = await myHandler(ctx, { method: 'POST', body: { … } })
+ *
+ * A ctx.sl / ctx.secrets / ctx.fetch call not covered by `def.capabilities` throws
+ * CapabilityError — exactly as it would in production.
+ */
+export function createFunctionTestContext(opts) {
+    var _a, _b, _c, _d;
+    const def = opts.def || {};
+    const parsed = parseCapabilities(def.capabilities || []);
+    const impl = opts.sl || {};
+    const logs = [];
+    const gated = (resource, op, fn, name) => async (...args) => {
+        if (!allowsSl(parsed, resource, op))
+            throw new CapabilityError(`sl:${resource}:${op}`);
+        return fn ? fn(...args) : stub(`${resource}.${name}`, args);
+    };
+    const ar = impl.appRecords || {};
+    const pr = impl.products || {};
+    const at = impl.attestations || {};
+    const sl = {
+        appRecords: {
+            create: gated('records', 'write', ar.create && ar.create.bind(ar), 'create'),
+            update: gated('records', 'write', ar.update && ar.update.bind(ar), 'update'),
+            upsert: gated('records', 'write', ar.upsert && ar.upsert.bind(ar), 'upsert'),
+            delete: gated('records', 'write', ar.delete && ar.delete.bind(ar), 'delete'),
+            get: gated('records', 'read', ar.get && ar.get.bind(ar), 'get'),
+            query: gated('records', 'read', ar.query && ar.query.bind(ar), 'query'),
+            listTypes: gated('records', 'read', ar.listTypes && ar.listTypes.bind(ar), 'listTypes'),
+        },
+        products: {
+            get: gated('products', 'read', pr.get && pr.get.bind(pr), 'get'),
+            query: gated('products', 'read', pr.query && pr.query.bind(pr), 'query'),
+            create: gated('products', 'write', pr.create && pr.create.bind(pr), 'create'),
+            update: gated('products', 'write', pr.update && pr.update.bind(pr), 'update'),
+        },
+        attestations: {
+            create: gated('attestations', 'write', at.create && at.create.bind(at), 'create'),
+        },
+    };
+    const secretsMap = opts.secrets || {};
+    const baseFetch = opts.fetch || (typeof fetch !== 'undefined' ? fetch : undefined);
+    const via = (def.trigger && def.trigger.type) || 'http';
+    const caller = opts.caller || {};
+    return {
+        collectionId: opts.collectionId || 'test-collection',
+        appId: opts.appId || 'test-app',
+        sl,
+        secrets: {
+            async get(ref) {
+                if (!parsed.secrets.has(ref))
+                    throw new CapabilityError(`secrets:${ref}`);
+                return Object.prototype.hasOwnProperty.call(secretsMap, ref) ? secretsMap[ref] : null;
+            },
+        },
+        caller: {
+            userId: (_a = caller.userId) !== null && _a !== void 0 ? _a : null,
+            anonymous: (_b = caller.anonymous) !== null && _b !== void 0 ? _b : !caller.userId,
+            origin: (_c = caller.origin) !== null && _c !== void 0 ? _c : null,
+            ip: (_d = caller.ip) !== null && _d !== void 0 ? _d : null,
+            via,
+        },
+        fetch: (async (input, init) => {
+            let host = '';
+            try {
+                host = new URL(typeof input === 'string' ? input : input.url).host;
+            }
+            catch ( /* bad URL → denied */_a) { /* bad URL → denied */ }
+            const allowed = parsed.networkAll || (!!host && parsed.networkHosts.has(host.toLowerCase()));
+            if (!allowed)
+                throw new CapabilityError(host ? `network:${host}` : 'network');
+            if (!baseFetch)
+                throw new Error('fetch is not available in this environment; pass opts.fetch');
+            return baseFetch(input, init);
+        }),
+        log: (message, data) => {
+            logs.push(Object.assign({ at: new Date().toISOString(), message: String(message) }, (data ? { data } : {})));
+        },
+        logs,
+    };
+}

package/dist/types/appManifest.d.ts

@@ -204,6 +204,113 @@ export interface AppManifestExecutor {
         responseShape?: Record<string, any>;
     };
 }
+/** What causes a server function to run. */
+export type AppFunctionTriggerType = 'http' | 'event' | 'cron';
+export interface AppFunctionTrigger {
+    type: AppFunctionTriggerType;
+    /** `event`: event types this function subscribes to, e.g. `['interaction.submitted:comp-entry']`. */
+    eventTypes?: string[];
+    /** `cron`: standard 5-field crontab expression, evaluated in UTC. */
+    schedule?: string;
+    /** `http`: URL path segment the function is exposed at (defaults to the function `name`). */
+    route?: string;
+    /** `http`: accepted HTTP methods (defaults to `['POST']`). */
+    methods?: Array<'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'>;
+}
+/** Who is allowed to invoke an `http`-triggered function. */
+export type AppFunctionVisibility = 'admin' | 'public';
+/**
+ * Whose authority the function runs with — i.e. what `ctx.sl` can do.
+ * - `caller`     — runs as the invoking user (their session/JWT). The secure default.
+ * - `collection` — runs with collection-admin authority over THIS collection only
+ *                  (never a global superuser). Required for `public` functions that
+ *                  must perform a privileged server-side action; the author is then
+ *                  responsible for validating input and preventing abuse.
+ */
+export type AppFunctionAuthority = 'caller' | 'collection';
+/** One server function declared in the manifest. */
+export interface AppFunctionDef {
+    /** Stable identifier, unique within the app, e.g. `'submitCompetitionEntry'`. */
+    name: string;
+    description?: string;
+    trigger: AppFunctionTrigger;
+    /**
+     * `http` only. `admin` = authenticated admin surface; `public` = publicly callable.
+     * Ignored for `event`/`cron` (no external caller). Defaults to `admin`.
+     */
+    visibility?: AppFunctionVisibility;
+    /**
+     * Whose authority `ctx.sl` carries. Defaults to `caller` (secure by default).
+     * `event`/`cron` functions have no caller and always run as `collection`.
+     */
+    authority?: AppFunctionAuthority;
+    /**
+     * Required acknowledgment for the sharp edge: a `public` + `collection` function is
+     * publicly callable AND runs with elevated collection authority. Set `elevated: true`
+     * to confirm you intend that and accept responsibility for validating requests —
+     * without it, install/validation fails. Ignored for any other visibility/authority combo.
+     */
+    elevated?: boolean;
+    /**
+     * Least-privilege capabilities this function needs, surfaced at install for
+     * consent and capped at runtime — even for `collection`-authority functions.
+     * e.g. `['sl:records:write', 'network:api.example.com', 'secrets:syndigo-key']`.
+     * Grammar: `sl:<resource>:<read|write>`, `network` (or `network:<host>`), `secrets:<ref>`.
+     */
+    capabilities?: string[];
+    /** SDK/manifest API version this function targets (pinned for runtime compatibility). */
+    apiVersion?: string;
+    /** Exported handler name in the functions bundle. Defaults to `name`. */
+    handler?: string;
+}
+/** The `functions` block in `app.manifest.json`. Presence means the app ships server functions. */
+export interface AppManifestFunctions {
+    files: AppManifestFiles;
+    definitions: AppFunctionDef[];
+}
+/** Identity of whoever invoked a server function. */
+export interface ServerFunctionCaller {
+    /** Authenticated user id, or `null` for anonymous/public/system invocations. */
+    userId: string | null;
+    /** True when no authenticated user is present (public/anonymous call, or event/cron). */
+    anonymous: boolean;
+    /** Request origin/referer, when available (`http` trigger). */
+    origin?: string | null;
+    /** Client IP, when available (`http` trigger). */
+    ip?: string | null;
+    /** How the function was triggered. */
+    via: AppFunctionTriggerType;
+}
+/**
+ * The context handed to every SmartLinks server function. The platform builds a
+ * fresh one per invocation and pre-scopes each handle to the function's declared
+ * authority + capabilities. The function receives only handles already narrowed
+ * to what it declared — no raw keys, no ambient superuser client.
+ */
+export interface ServerFunctionContext {
+    collectionId: string;
+    appId: string;
+    /**
+     * SmartLinks SDK, pre-scoped to the function's declared `authority`:
+     *  - `caller`     → scoped to the invoking user (their JWT).
+     *  - `collection` → scoped to a collection-admin principal for THIS collection
+     *                   only — never a global superuser.
+     * Declared `capabilities` cap what these calls may do.
+     */
+    sl: any;
+    /** Capability-gated secret access. `get(ref)` resolves only refs granted via `secrets:<ref>`. */
+    secrets: {
+        get(ref: string): Promise<string | null>;
+    };
+    /** Who invoked this function. */
+    caller: ServerFunctionCaller;
+    /** Outbound HTTP — present only when the `network` capability is declared (host-scoped if `network:<host>`). */
+    fetch: typeof fetch;
+    /** Structured logging captured into run telemetry. */
+    log: (message: string, data?: Record<string, any>) => void;
+}
+/** The signature every SmartLinks server function implements. */
+export type ServerFunctionHandler<TEvent = any, TResult = any> = (ctx: ServerFunctionContext, event: TEvent) => Promise<TResult> | TResult;
 /**
  * Shape of `app.admin.json` -- the separate admin configuration file pointed to
  * by `AppManifest.admin`. Fetch this file yourself when you need setup / import /
@@ -342,6 +449,13 @@ export interface AppManifest {
      * @see AppManifestExecutor
      */
     executor?: AppManifestExecutor;
+    /**
+     * Server functions ("edge functions") this app deploys into SmartLinks —
+     * arbitrary server-side code triggered by http, events, or cron, each running
+     * with a declared authority + least-privilege capabilities.
+     * @see AppManifestFunctions
+     */
+    functions?: AppManifestFunctions;
     [key: string]: any;
 }
 /**

package/dist/types/integrations.d.ts

@@ -134,3 +134,11 @@ export interface SetSecretResult {
 export interface ListSecretsQuery {
     purpose?: string;
 }
+export interface RecordTypeInfo {
+    appId: string;
+    recordType: string;
+    count: number;
+}
+export interface RecordTypesResponse {
+    recordTypes: RecordTypeInfo[];
+}