primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/types/index.d.ts

@@ -0,0 +1,591 @@
+export interface Credentials {
+    serverUrl: string;
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: string;
+    adminId: string;
+    email: string;
+    role: "admin" | "super-admin";
+    name?: string;
+    globalAdminAppId?: string;
+}
+export interface AppSummary {
+    appId: string;
+    name: string;
+    mode?: string;
+}
+/** One entry of the `googleClients` map (#2891). */
+export interface GoogleClientSetting {
+    clientId: string;
+    /** Whole `{{secrets.KEY}}` reference; absent for the native client types. */
+    clientSecret?: string | null;
+    redirectUris: string[];
+}
+/**
+ * `[auth.google]` — the client map, keyed by Google client type (`web`, `ios`,
+ * `android`, `desktop`, `chrome-extension`). The `clients` wrapper keeps
+ * `[auth.google]` open for a later sibling key.
+ */
+export interface GoogleClientsSetting {
+    clients: Record<string, GoogleClientSetting>;
+}
+export interface AppSettings {
+    name: string;
+    baseUrl?: string | null;
+    mode: "public" | "invite-only" | "domain";
+    waitlistEnabled?: boolean;
+    allowedDomains?: string[] | null;
+    emailRedirectUris?: string[] | null;
+    googleOAuthEnabled?: boolean;
+    googleClients?: GoogleClientsSetting | null;
+    corsMode?: "universal" | "custom";
+    corsAllowedOrigins?: string[] | null;
+    corsAllowCredentials?: boolean;
+    corsAllowedMethods?: string[] | null;
+    corsAllowedHeaders?: string[] | null;
+    corsExposedHeaders?: string[] | null;
+    corsMaxAge?: number | null;
+    passkeyEnabled?: boolean;
+    passkeyRpConfig?: Record<string, {
+        name: string;
+    }> | null;
+    hasPasskey?: boolean;
+    emailSignInEnabled?: boolean;
+    /** @deprecated (#2884) Response-only; always equal to `emailSignInEnabled`. */
+    magicLinkEnabled?: boolean;
+    /** @deprecated (#2884) Response-only; always equal to `emailSignInEnabled`. */
+    otpEnabled?: boolean;
+    appleSignInEnabled?: boolean | null;
+    appleAudiences?: string[] | null;
+}
+export interface User {
+    userId: string;
+    email: string;
+    name: string;
+    role: "owner" | "admin" | "member";
+    addedAt: string;
+}
+export interface Invitation {
+    invitationId: string;
+    email: string;
+    role: "admin" | "member";
+    createdAt: string;
+    expiresAt: string;
+    invitedBy: string;
+    accepted?: boolean;
+    acceptedAt?: string;
+}
+export interface WaitlistEntry {
+    waitlistId: string;
+    email: string;
+    displayName?: string | null;
+    provider?: string | null;
+    providerId?: string | null;
+    source?: string | null;
+    note?: string | null;
+    requestedAt?: string | null;
+    updatedAt?: string | null;
+}
+export interface MultipartFieldDefinition {
+    fieldName: string;
+    type: "attachment" | "value";
+    attachmentIndex?: number;
+    attachmentName?: string;
+    value?: string;
+}
+export interface IntegrationRequestConfig {
+    baseUrl: string;
+    allowedMethods?: string[];
+    allowedPaths?: string[];
+    defaultMethod?: string;
+    defaultHeaders?: Record<string, string>;
+    staticQuery?: Record<string, any>;
+    forwardHeaders?: string[];
+    forwardQueryParams?: string[];
+    responsePassthrough?: boolean;
+    exampleQuery?: Record<string, any>;
+    exampleBody?: any;
+    bodyMode?: "json" | "raw" | "multipart";
+    multipartFieldMapping?: MultipartFieldDefinition[];
+}
+export interface IntegrationSummary {
+    integrationId: string;
+    integrationKey: string;
+    displayName: string;
+    status: string;
+    lastTestedAt?: string | null;
+    createdAt?: string;
+    modifiedAt?: string;
+}
+export interface IntegrationDetail extends IntegrationSummary {
+    appId: string;
+    description?: string | null;
+    requestConfig: IntegrationRequestConfig;
+    timeoutMs?: number;
+    maxRequestBodyBytes?: number;
+}
+export interface IntegrationTestPayload {
+    method?: string;
+    path?: string;
+    query?: Record<string, any>;
+    headers?: Record<string, string>;
+    body?: any;
+}
+export interface IntegrationTestResult {
+    success: boolean;
+    upstreamResponse?: {
+        status: number;
+        headers: Record<string, string>;
+        body: any;
+        traceId?: string;
+        durationMs?: number;
+    };
+    errorCode?: string;
+    message?: string;
+    traceId?: string;
+}
+export interface IntegrationLogEntry {
+    timestamp: string;
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+    traceId: string;
+    errorCode?: string;
+    actorType?: string;
+    actorId?: string;
+}
+export interface Webhook {
+    webhookId: string;
+    webhookKey: string;
+    displayName: string;
+    description?: string;
+    status: string;
+    workflowKey: string;
+    verificationScheme: string;
+    signingSecret?: string | null;
+    previousSigningSecret?: string | null;
+    signingSecretStatus?: "reference" | "legacy-literal" | "malformed-reference" | "unset";
+    previousSigningSecretStatus?: "reference" | "legacy-literal" | "malformed-reference" | "unset";
+    signingSecretHealth?: "ok" | "weak-literal" | (string & {});
+    previousSigningSecretHealth?: "ok" | "weak-literal" | (string & {});
+    secretRotatedAt?: string | null;
+    toleranceSeconds: number;
+    deduplicationEnabled: boolean;
+    deduplicationWindowMs: number;
+    maxBodyBytes?: number | null;
+    secretGracePeriodMs: number;
+    inputMapping?: string;
+    allowedIpCidrs?: string;
+    metadata?: string;
+    lastTriggeredAt?: string;
+    createdAt: string;
+    modifiedAt: string;
+}
+export interface WebhookEvent {
+    eventId: string;
+    /** The provider's own delivery id — display and correlation only. */
+    externalEventId?: string;
+    /**
+     * The replay-suppression key the platform derived from the signed payload.
+     * Present on `accepted` deliveries only — a `duplicate` row carries none, so
+     * the `duplicate` status is itself the "this delivery was suppressed" signal
+     * and this key identifies which accepted delivery it collapsed into.
+     *
+     * It always begins with a reserved tag naming which domain it came from:
+     * `sha256:` a digest the platform computed over the signed payload, `id:` an
+     * identifier the delivery itself carried, `cap:` the rehash of a key too long
+     * for the index. The tags keep the domains from overlapping, so a carried id
+     * can never name a platform digest.
+     */
+    dedupKey?: string | null;
+    status: string;
+    httpStatus: number;
+    sourceIp?: string;
+    payloadSummary?: string;
+    rejectionReason?: string;
+    workflowRunKey?: string;
+    processingDurationMs?: number;
+    createdAt: string;
+}
+export interface Workflow {
+    workflowId: string;
+    workflowKey: string;
+    name: string;
+    description: string | null;
+    status: "draft" | "active" | "archived";
+    activeConfigId: string | null;
+    latestRevision: string | null;
+    inputSchema: object | null;
+    outputSchema: object | null;
+    perUserMaxRunning: number;
+    perUserMaxQueued: number;
+    perAppMaxRunning: number;
+    perAppMaxQueued: number;
+    queueTtlSeconds: number;
+    dequeueOrder: "fifo" | "lifo";
+    createdBy: string;
+    createdAt: string;
+    modifiedAt: string;
+}
+export interface WorkflowDraft {
+    steps: any[];
+    inputSchema: object | null;
+    outputSchema: object | null;
+}
+export interface WorkflowRevision {
+    revisionId: string;
+    workflowId: string;
+    stepsR2Key: string;
+    inputSchema: object | null;
+    outputSchema: object | null;
+    publishedAt: string | null;
+    createdBy: string;
+    createdAt: string;
+}
+export interface WorkflowRun {
+    runId: string;
+    runKey: string;
+    instanceId: string;
+    workflowId: string;
+    workflowKey: string;
+    revisionId: string;
+    contextDocId: string;
+    status: string;
+    startedAt: string | null;
+    endedAt: string | null;
+    startedByUserId?: string;
+    input: any | null;
+    meta: object | null;
+    isPreview?: boolean;
+}
+export interface WorkflowInstanceStatus {
+    status: string;
+    output?: any;
+    stepResults?: Array<{
+        id: string;
+        kind: string;
+        output: any;
+        startedAt: string;
+        endedAt: string;
+        durationMs: number;
+        skipped?: boolean;
+    }>;
+    error?: any;
+}
+export interface AppPromptSummary {
+    promptId: string;
+    promptKey: string;
+    displayName: string;
+    description?: string | null;
+    activeConfigId?: string | null;
+    defaultEvaluatorPromptId?: string | null;
+    status: "draft" | "active" | "archived";
+    createdAt?: string;
+    modifiedAt?: string;
+}
+export interface AppPromptDetail extends AppPromptSummary {
+    appId: string;
+    copiedFromCatalogId?: string | null;
+    inputSchema?: string | null;
+    createdBy?: string;
+    configs: AppPromptConfig[];
+}
+export interface AppPromptConfig {
+    configId: string;
+    promptId: string;
+    appId: string;
+    configName: string;
+    description?: string | null;
+    provider: "openrouter" | "gemini";
+    model: string;
+    systemPrompt?: string | null;
+    userPromptTemplate: string;
+    temperature?: number | null;
+    topP?: number | null;
+    maxTokens?: number | null;
+    outputSchema?: object | null;
+    providerConfig?: object | null;
+    status: "active" | "archived";
+    createdBy?: string;
+    createdAt?: string;
+    modifiedAt?: string;
+}
+export interface PromptExecuteResult {
+    success: boolean;
+    output: string;
+    rawResponse: any;
+    error?: string;
+    configId?: string;
+    metrics: {
+        durationMs: number;
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+}
+export interface PromptPreviewResult {
+    systemPrompt?: string;
+    userPrompt: string;
+    model?: string;
+    provider?: string;
+    configId?: string;
+}
+export interface AnalyticsOverviewResponse {
+    windowDays: number;
+    bucketDays: number;
+    totals: {
+        dau: number;
+        wau: number;
+        mau: number;
+        totalEvents: number;
+    };
+    series: Array<{
+        bucketStart: string;
+        activeUsers: number;
+        totalEvents: number;
+    }>;
+}
+export interface AnalyticsTopUsersResponse {
+    windowDays: number;
+    limit: number;
+    results: Array<{
+        userUlid: string;
+        /** First event ever recorded for the user — does not move with windowDays (#3126). */
+        firstSeen: string;
+        /** First event inside windowDays — the window-relative counterpart. */
+        firstSeenInWindow: string;
+        lastSeen: string;
+        eventCount: number;
+    }>;
+}
+export interface AnalyticsUserTimelineResponse {
+    windowDays: number;
+    bucketSeconds: number;
+    timeline: Array<{
+        bucketStart: string;
+        events: number;
+    }>;
+    breakdown: Array<{
+        action: string;
+        feature: string;
+        route: string;
+        events: number;
+    }>;
+}
+export interface AnalyticsIntegrationMetricsResponse {
+    windowDays: number;
+    integrations: Array<{
+        integrationKey: string;
+        invocations: number;
+        errorRate: number;
+        avgDurationMs: number;
+        p95DurationMs: number;
+    }>;
+}
+export interface AdminSummary {
+    adminId: string;
+    email: string;
+    name: string;
+    role: string;
+    appCreationLimit: number;
+    disabledAt?: string | null;
+    assignedAppsCount: number;
+    createdAppsCount: number;
+}
+export interface AdminInvitation {
+    invitationId: string;
+    email: string;
+    invitedAt?: string;
+    expiresAt?: string;
+    invitedBy?: string | null;
+    type: "global" | "app";
+    appId?: string;
+    appName?: string;
+    appCreationLimit?: number;
+}
+export interface PromptCatalogItem {
+    catalogId: string;
+    catalogKey: string;
+    displayName: string;
+    description?: string | null;
+    category?: string | null;
+    provider: "openrouter" | "gemini";
+    model: string;
+    systemPrompt?: string | null;
+    userPromptTemplate: string;
+    inputSchema?: string | null;
+    outputSchema?: string | null;
+    temperature?: string | null;
+    topP?: string | null;
+    maxTokens?: number | null;
+    status: "draft" | "active" | "deprecated";
+    createdBy?: string;
+    createdAt?: string;
+    modifiedAt?: string;
+}
+export interface IntegrationCatalogItem {
+    catalogId: string;
+    catalogKey: string;
+    displayName: string;
+    description?: string | null;
+    category?: string | null;
+    requestConfig: string;
+    docUrl?: string | null;
+    logoUrl?: string | null;
+    status: "draft" | "active" | "deprecated";
+    createdBy?: string;
+    createdAt?: string;
+    modifiedAt?: string;
+}
+export interface WorkflowConfiguration {
+    configId: string;
+    workflowId: string;
+    appId: string;
+    configName: string;
+    description?: string | null;
+    stepsR2Key: string;
+    status: "active" | "archived";
+    steps?: any[];
+    createdBy?: string;
+    createdAt?: string;
+    modifiedAt?: string;
+}
+export interface SyncState {
+    appId: string;
+    serverUrl: string;
+    lastSyncedAt: string;
+    entities: {
+        app?: {
+            modifiedAt: string;
+            contentHash?: string;
+            semanticHash?: string;
+            /**
+             * The `[app].name` a cross-app push deliberately did NOT send (DSO-001).
+             * While this is set and the file still states this name, `name` is out of
+             * the comparison, out of the payload, and out of the baseline hash. A file
+             * stating a different name is a local rename: the exclusion clears and the
+             * baseline is restamped with `name`.
+             *
+             * Held as the file STATED it rather than as text (#2936): the excluded
+             * line is stripped before validation, so a cross-app push can leave a
+             * `name = 123` behind, and the same file has to keep reading as the same
+             * name on the next run.
+             */
+            excludedName?: unknown;
+        };
+        integrations?: Record<string, {
+            id: string;
+            modifiedAt: string;
+            contentHash?: string;
+            semanticHash?: string;
+        }>;
+        prompts?: Record<string, {
+            id: string;
+            modifiedAt: string;
+            contentHash?: string;
+            semanticHash?: string;
+        }>;
+        workflows?: Record<string, {
+            id: string;
+            modifiedAt: string;
+            activeConfigId?: string;
+            contentHash?: string;
+        }>;
+        emailTemplates?: Record<string, {
+            id: string;
+            modifiedAt: string;
+            contentHash?: string;
+            semanticHash?: string;
+        }>;
+        testCases?: Record<string, {
+            id: string;
+            blockType: string;
+            blockId: string;
+            blockKey: string;
+            slug: string;
+            modifiedAt: string;
+            /**
+             * Pre-#2769 attachment tracking: names only, so a byte change under an
+             * unchanged name was invisible. Still read, so an existing sync state
+             * upgrades without a re-pull (the files re-upload once, then converge).
+             */
+            attachmentFilenames?: string[];
+            /** filename → content hash of the attachment last synced (#2769). */
+            attachments?: Record<string, string>;
+            contentHash?: string;
+            semanticHash?: string;
+        }>;
+        databaseTypes?: Record<string, {
+            databaseType: string;
+            modifiedAt: string;
+            operations?: Record<string, {
+                modifiedAt: string;
+            }>;
+            subscriptions?: Record<string, {
+                modifiedAt: string;
+            }>;
+            contentHash?: string;
+            semanticHash?: string;
+            hasSchema?: boolean;
+        }>;
+        ruleSets?: Record<string, {
+            id: string;
+            modifiedAt: string;
+            contentHash?: string;
+            semanticHash?: string;
+        }>;
+        vars?: Record<string, {
+            modifiedAt: string;
+            contentHash?: string;
+        }>;
+        groupTypeConfigs?: Record<string, {
+            modifiedAt: string;
+            contentHash?: string;
+            semanticHash?: string;
+        }>;
+        collectionTypeConfigs?: Record<string, {
+            modifiedAt: string;
+            contentHash?: string;
+            semanticHash?: string;
+        }>;
+        metadataCategoryConfigs?: Record<string, {
+            modifiedAt: string;
+            contentHash?: string;
+            semanticHash?: string;
+        }>;
+        webhooks?: Record<string, {
+            id: string;
+            modifiedAt: string;
+            contentHash?: string;
+            semanticHash?: string;
+        }>;
+        blobBuckets?: Record<string, {
+            id: string;
+            modifiedAt: string;
+            contentHash?: string;
+            semanticHash?: string;
+        }>;
+        cronTriggers?: Record<string, {
+            id: string;
+            modifiedAt: string;
+            contentHash?: string;
+            semanticHash?: string;
+        }>;
+        scripts?: Record<string, {
+            id: string;
+            modifiedAt: string;
+            contentHash?: string;
+            semanticHash?: string;
+        }>;
+        functions?: Record<string, {
+            id: string;
+            modifiedAt: string;
+            contentHash?: string;
+            semanticHash?: string;
+            envelopeHash?: string;
+            activeConfigId?: string;
+            sources?: string[];
+        }>;
+    };
+}

package/dist/src/validators.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Public subpath export: `primitive-admin/validators` (issue #983).
+ *
+ * Re-exports the TOML validators that `config push` runs as its load-bearing
+ * gate, so external tooling (e.g. `primitive-docs`) can validate the exact
+ * same way the published CLI does — instead of re-implementing the parse /
+ * expand / validate flow against submodule source and silently drifting.
+ *
+ * Two kinds of entry points are exported:
+ *
+ *  1. `validateWorkflowTomlSource(raw, filePath)` — the **source-level**
+ *     wrapper. Runs the identical parse → fragment-expand → validate → format
+ *     path that `config push` runs for workflow TOML (`cli/src/commands/sync.ts`:
+ *     `parseTomlFile()` → `validateWorkflowToml()` → `formatWorkflowTomlErrors()`).
+ *     Use this when you have the raw TOML string and want zero divergence from
+ *     `config push`, including `include` fragment expansion.
+ *
+ *  2. The raw validators (`validateWorkflowToml`, `validateOperations`) and
+ *     their formatters (`formatWorkflowTomlErrors`, `formatIssue`). These are
+ *     **pure functions over already-parsed TOML** — they do not read files or
+ *     parse TOML themselves. The consumer is responsible for parsing (config
+ *     files via `parseConfigToml`) and, for workflows, for any `include`
+ *     expansion. There is
+ *     no coupling on a specific TOML parser version; pass whatever parsed
+ *     object/operations[] you already have.
+ *
+ * Internal helpers (`collectParamRefs`, `declaredParamNames`,
+ * `locateOperationLine`) are intentionally NOT exported — they are
+ * implementation details of `validateOperations`.
+ */
+import { type WorkflowTomlError } from "./lib/workflow-toml-validator.js";
+export { validateWorkflowToml, formatWorkflowTomlErrors, type WorkflowTomlError, } from "./lib/workflow-toml-validator.js";
+export { validateOperations, formatIssue, type ValidationIssue, type ValidationResult, type ValidateOptions, } from "./lib/toml-params-validator.js";
+/**
+ * Result of {@link validateWorkflowTomlSource}.
+ */
+export interface WorkflowTomlSourceResult {
+    /** The structured errors (empty when the source is valid). */
+    errors: WorkflowTomlError[];
+    /**
+     * A human-readable, multi-line error string (the same text `config push`
+     * prints), or `null` when there are no errors.
+     */
+    formatted: string | null;
+}
+/**
+ * Validate a workflow TOML **source string** the exact way `config push` does.
+ *
+ * Runs the identical pipeline `config push` runs on every workflow file:
+ *   `parseConfigToml(raw)` → `expandWorkflowTomlData(parsed, filePath)`
+ *   → `validateWorkflowToml(expanded)` → `formatWorkflowTomlErrors(...)`.
+ *
+ * The `include` fragment expansion resolves fragments relative to
+ * `<filePath>/../../workflow-fragments/` — pass the real (or intended) on-disk
+ * path of the workflow so fragment resolution matches `config push`. If the
+ * source uses no `include` key the expander is a no-op and `filePath` is only
+ * used for error attribution.
+ *
+ * @param raw The raw workflow TOML source string.
+ * @param filePath The workflow's file path (used for fragment resolution and
+ *   error attribution).
+ * @returns `{ errors, formatted }` — `errors` is empty and `formatted` is
+ *   `null` when the source is valid.
+ */
+export declare function validateWorkflowTomlSource(raw: string, filePath: string): WorkflowTomlSourceResult;