@newhomestar/sdk 0.5.2 → 0.6.5

package/dist/integration.js

@@ -0,0 +1,416 @@
+// nova-sdk – Integration Definition API
+// =====================================================
+// Code-first integration definitions with Zod schemas.
+// Integrations are containerized services (like workers) that ALSO
+// carry schema/event/function configuration synced to the platform DB.
+//
+// TWO API styles supported:
+//   Verbose:  integrationSchema({ name, slug, schemaType, schema, version })
+//   Lean:     schema("entity", z.object({...}))  ← slug/name inferred from key
+// -----------------------------------------------------------
+import { z } from "zod";
+/** Symbol used to tag lean schema/event wrappers (non-enumerable) */
+const NOVA_SCHEMA = Symbol.for('nova.schema');
+const NOVA_EVENT = Symbol.for('nova.event');
+/**
+ * **Verbose** helper — define a schema with all metadata explicitly.
+ *
+ * @example
+ * ```ts
+ * const WorkerProfile = integrationSchema({
+ *   name: "Worker Profile",
+ *   slug: "worker_profile",
+ *   schemaType: "entity",
+ *   schema: z.object({ workerId: z.string() }),
+ * });
+ * ```
+ */
+export function integrationSchema(cfg) {
+    return cfg;
+}
+/**
+ * **Lean** helper — slug and name are inferred from the key in `schemas: {}`.
+ *
+ * @example
+ * ```ts
+ * const User = schema("entity", z.object({
+ *   id: z.string(),
+ *   email: z.string().email(),
+ * }));
+ *
+ * // In defineIntegration:
+ * schemas: { user: User }
+ * //  → slug: "user", name: "User", schemaType: "entity"
+ * ```
+ */
+export function schema(schemaType, zodSchema, opts) {
+    const def = {
+        name: '', // filled from key by defineIntegration()
+        slug: '', // filled from key by defineIntegration()
+        schemaType,
+        schema: zodSchema,
+        version: opts?.version ?? '1.0.0',
+        description: opts?.description,
+        shape: zodSchema, // convenience alias for direct Zod reference
+    };
+    Object.defineProperty(def, NOVA_SCHEMA, { value: true, enumerable: false });
+    return def;
+}
+/**
+ * **Verbose** helper — define an event with all metadata explicitly.
+ *
+ * @example
+ * ```ts
+ * const workerHire = integrationEvent({
+ *   slug: "worker.hire",
+ *   name: "Worker Hired",
+ *   direction: "inbound",
+ *   category: "lifecycle",
+ *   severity: "info",
+ *   payloadSchema: "new_hire_payload",
+ * });
+ * ```
+ */
+export function integrationEvent(cfg) {
+    return cfg;
+}
+/**
+ * **Lean** helper — slug and name inferred from key in `events: {}`.
+ * Payload can reference a `schema()` result directly (type-safe, no strings).
+ *
+ * @example
+ * ```ts
+ * const User = schema("entity", z.object({ id: z.string() }));
+ *
+ * // In defineIntegration:
+ * events: {
+ *   user_synced: event("outbound", { payload: User }),
+ *   sync_failed: event("outbound", { severity: "error" }),
+ * }
+ * ```
+ */
+export function event(direction, opts) {
+    const def = {
+        slug: '', // filled from key by defineIntegration()
+        name: '', // filled from key by defineIntegration()
+        direction,
+        severity: opts?.severity,
+        category: opts?.category,
+        description: opts?.description,
+    };
+    // Store payload reference for resolution during normalization
+    if (opts?.payload) {
+        Object.defineProperty(def, '__payloadRef', { value: opts.payload, enumerable: false });
+    }
+    Object.defineProperty(def, NOVA_EVENT, { value: true, enumerable: false });
+    return def;
+}
+/**
+ * Helper to define an integration function (API endpoint).
+ *
+ * @example
+ * ```ts
+ * const listWorkers = integrationFunction({
+ *   slug: "list_workers",
+ *   name: "List Workers",
+ *   httpMethod: "GET",
+ *   endpointPath: "/hr/v2/workers",
+ *   responseSchema: "worker_profile",
+ *   requiredScopes: ["api"],
+ *   category: "workers",
+ * });
+ * ```
+ */
+export function integrationFunction(cfg) {
+    return cfg;
+}
+/*─────────────────────────*  Zod Validation Schema  *──────────────────────────*/
+const IntegrationSchemaDefSchema = z.object({
+    name: z.string(),
+    slug: z.string().regex(/^[a-z][a-z0-9_]*$/, 'Schema slug must be snake_case'),
+    description: z.string().optional(),
+    schemaType: z.enum(['request', 'response', 'entity', 'webhook_payload', 'configuration']),
+    schema: z.any(), // Zod schema instance
+    version: z.string().optional(),
+});
+const IntegrationEventDefSchema = z.object({
+    slug: z.string(),
+    name: z.string(),
+    direction: z.enum(['inbound', 'outbound', 'bidirectional']),
+    description: z.string().optional(),
+    category: z.string().optional(),
+    severity: z.enum(['info', 'warning', 'error', 'critical']).optional(),
+    payloadSchema: z.string().optional(),
+});
+const IntegrationFunctionDefSchema = z.object({
+    slug: z.string().regex(/^[a-z][a-z0-9_]*$/, 'Function slug must be snake_case'),
+    name: z.string(),
+    httpMethod: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']),
+    endpointPath: z.string(),
+    description: z.string().optional(),
+    requestSchema: z.string().optional(),
+    responseSchema: z.string().optional(),
+    requiredScopes: z.array(z.string()).optional(),
+    category: z.string().optional(),
+    capabilities: z.array(z.union([z.string(), z.record(z.string(), z.unknown())])).optional(),
+});
+export const IntegrationDefSchema = z.object({
+    slug: z.string().regex(/^[a-z][a-z0-9_]*$/, 'Integration slug must be snake_case'),
+    name: z.string(),
+    description: z.string().optional(),
+    integrationType: z.enum(['oidc', 'oauth2', 'api_key']),
+    category: z.string().optional(),
+    logoUrl: z.string().optional(),
+    color: z.string().optional(),
+    authorizationEndpoint: z.string().optional(),
+    tokenEndpoint: z.string().optional(),
+    userinfoEndpoint: z.string().optional(),
+    revocationEndpoint: z.string().optional(),
+    jwksUri: z.string().optional(),
+    baseUrl: z.string().optional(),
+    scopes: z.array(z.string()).optional(),
+    queue: z.string(),
+    displayName: z.string().optional(),
+    icon: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    ui: z.object({
+        category: z.string().optional(),
+        color: z.string().optional(),
+    }).optional(),
+    resources: z.object({
+        cpu: z.string(),
+        memory: z.string(),
+    }).optional(),
+    envSpec: z.array(z.object({
+        name: z.string(),
+        secret: z.boolean(),
+        default: z.string().optional(),
+    })).optional(),
+    actions: z.record(z.string(), z.any()),
+    schemas: z.record(z.string(), IntegrationSchemaDefSchema),
+    events: z.record(z.string(), IntegrationEventDefSchema),
+    functions: z.record(z.string(), IntegrationFunctionDefSchema),
+});
+/**
+ * Validate an integration definition before build or push.
+ *
+ * Performs conditional validation based on `integrationType`:
+ * - **Always required**: slug, name, queue, baseUrl, ≥1 action
+ * - **OAuth2/OIDC required**: authorizationEndpoint, tokenEndpoint
+ * - **OIDC warned**: jwksUri, userinfoEndpoint
+ * - **Warnings**: no schemas, no scopes, non-HTTPS URLs, no health action
+ *
+ * Called automatically during `nova integrations build` and `nova integrations push`.
+ *
+ * @example
+ * ```ts
+ * const result = validateIntegration(myIntegration);
+ * if (!result.valid) {
+ *   result.errors.forEach(e => console.error(`❌ ${e}`));
+ *   process.exit(1);
+ * }
+ * result.warnings.forEach(w => console.warn(`⚠️  ${w}`));
+ * ```
+ */
+export function validateIntegration(def) {
+    const errors = [];
+    const warnings = [];
+    // ── Always required ──
+    if (!def.slug)
+        errors.push("'slug' is required");
+    if (!def.name)
+        errors.push("'name' is required");
+    if (!def.queue)
+        errors.push("'queue' is required");
+    if (!def.baseUrl || def.baseUrl.trim() === '') {
+        errors.push("'baseUrl' is required — the base URL for API calls (e.g., https://api.example.com)");
+    }
+    if (!def.actions || Object.keys(def.actions).length === 0) {
+        errors.push("at least one action is required");
+    }
+    // ── OAuth2 / OIDC specific ──
+    if (def.integrationType === 'oauth2' || def.integrationType === 'oidc') {
+        if (!def.authorizationEndpoint || def.authorizationEndpoint.trim() === '') {
+            errors.push(`'authorizationEndpoint' is required for ${def.integrationType} integrations`);
+        }
+        if (!def.tokenEndpoint || def.tokenEndpoint.trim() === '') {
+            errors.push(`'tokenEndpoint' is required for ${def.integrationType} integrations`);
+        }
+        if (!def.scopes || def.scopes.length === 0) {
+            warnings.push(`no 'scopes' defined for ${def.integrationType} integration — most providers require at least one`);
+        }
+    }
+    // ── OIDC specific ──
+    if (def.integrationType === 'oidc') {
+        if (!def.jwksUri) {
+            warnings.push("'jwksUri' not set for OIDC integration — required for token verification");
+        }
+        if (!def.userinfoEndpoint) {
+            warnings.push("'userinfoEndpoint' not set for OIDC integration");
+        }
+    }
+    // ── URL format validation ──
+    const urlFields = [
+        ['authorizationEndpoint', def.authorizationEndpoint],
+        ['tokenEndpoint', def.tokenEndpoint],
+        ['baseUrl', def.baseUrl],
+        ['userinfoEndpoint', def.userinfoEndpoint],
+        ['revocationEndpoint', def.revocationEndpoint],
+        ['jwksUri', def.jwksUri],
+    ];
+    for (const [fieldName, value] of urlFields) {
+        if (value && value.trim() !== '' && !value.startsWith('https://') && !value.startsWith('http://localhost')) {
+            warnings.push(`'${fieldName}' should use HTTPS: "${value}"`);
+        }
+    }
+    // ── Structural checks ──
+    if (!def.schemas || Object.keys(def.schemas).length === 0) {
+        warnings.push("no schemas defined — consider adding at least one entity schema");
+    }
+    if (def.actions && !def.actions['health'] && !def.actions['healthCheck']) {
+        warnings.push("no 'health' action defined — recommended for all integrations");
+    }
+    if (!def.envSpec || def.envSpec.length === 0) {
+        warnings.push("no 'envSpec' defined — environment variables won't be validated at deploy time");
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+/*─────────────────────────*  defineIntegration()  *──────────────────────────*/
+/**
+ * Register an integration definition — the single source of truth for both
+ * the containerized runtime AND the platform configuration.
+ *
+ * @example
+ * ```ts
+ * export default defineIntegration({
+ *   slug: "adp_workforce_now",
+ *   name: "ADP Workforce Now",
+ *   integrationType: "oidc",
+ *   queue: "adp_integration_queue",
+ *   schemas: { ... },
+ *   events: { ... },
+ *   functions: { ... },
+ *   actions: {
+ *     health: action({ ... }),
+ *     handleWebhook: action({ ... }),
+ *   },
+ * });
+ * ```
+ */
+/** Convert a key like "user_profile" → "User Profile" */
+function slugToName(slug) {
+    return slug
+        .replace(/_/g, ' ')
+        .replace(/\b\w/g, c => c.toUpperCase());
+}
+/** Convert camelCase key like "listUsers" → "list_users" */
+function camelToSnake(str) {
+    return str.replace(/([A-Z])/g, '_$1').toLowerCase().replace(/^_/, '');
+}
+export function defineIntegration(def) {
+    // ── Phase 1: Normalize lean schemas ──
+    // Fill slug/name from the key when using schema() helper
+    for (const [key, schemaDef] of Object.entries(def.schemas)) {
+        if (!schemaDef.slug || schemaDef.slug === '') {
+            schemaDef.slug = key;
+        }
+        if (!schemaDef.name || schemaDef.name === '') {
+            schemaDef.name = slugToName(key);
+        }
+    }
+    // ── Phase 2: Normalize lean events ──
+    // Fill slug/name from the key and resolve payload references
+    for (const [key, eventDef] of Object.entries(def.events)) {
+        if (!eventDef.slug || eventDef.slug === '') {
+            eventDef.slug = key;
+        }
+        if (!eventDef.name || eventDef.name === '') {
+            eventDef.name = slugToName(key);
+        }
+        // Resolve direct payload reference → schema slug string
+        const payloadRef = eventDef.__payloadRef;
+        if (payloadRef && !eventDef.payloadSchema) {
+            for (const [schemaKey, schemaDef] of Object.entries(def.schemas)) {
+                if (schemaDef === payloadRef ||
+                    schemaDef.shape === payloadRef ||
+                    schemaDef.schema === payloadRef) {
+                    eventDef.payloadSchema = schemaKey;
+                    break;
+                }
+            }
+        }
+    }
+    // ── Phase 3: Auto-extract functions from ALL actions ──
+    // Every action is promoted to a function entry so it's synced to the DB
+    // and visible in the Service Mode tester. Actions with scopes get those
+    // recorded; actions without scopes (e.g., health, handleWebhook) are
+    // still registered so the admin UI can discover and invoke them.
+    if (!def.functions) {
+        def.functions = {};
+    }
+    for (const [key, actionDef] of Object.entries(def.actions)) {
+        const snakeKey = camelToSnake(key);
+        // Skip if already explicitly declared in functions map
+        if (def.functions[snakeKey])
+            continue;
+        const scopes = actionDef.scopes || actionDef.requiredScopes;
+        const fnEntry = {
+            slug: snakeKey,
+            name: slugToName(snakeKey),
+            httpMethod: (actionDef.method || 'POST').toUpperCase(),
+            endpointPath: actionDef.path || `/${snakeKey}`,
+            description: actionDef.description || '',
+            requiredScopes: scopes && Array.isArray(scopes) ? scopes : [],
+            category: actionDef.category || '',
+            capabilities: actionDef.capabilities || [],
+        };
+        def.functions[snakeKey] = fnEntry;
+        // Store Zod input/output as non-enumerable props for build step to
+        // convert to JSON Schema → inputSchema / outputSchema DB columns.
+        if (actionDef.input) {
+            Object.defineProperty(fnEntry, '__inputZod', {
+                value: actionDef.input,
+                enumerable: false,
+            });
+        }
+        if (actionDef.output) {
+            Object.defineProperty(fnEntry, '__outputZod', {
+                value: actionDef.output,
+                enumerable: false,
+            });
+        }
+        // Store params metadata for the CLI build step to embed
+        // x-nova-* extensions into JSON Schema output.
+        if (actionDef.params) {
+            Object.defineProperty(fnEntry, '__paramsMeta', {
+                value: actionDef.params,
+                enumerable: false,
+            });
+        }
+    }
+    // ── Phase 4: Validate with Zod ──
+    IntegrationDefSchema.parse(def);
+    // ── Phase 5: Cross-validate schema references in events ──
+    for (const [eventKey, eventDef] of Object.entries(def.events)) {
+        if (eventDef.payloadSchema && !def.schemas[eventDef.payloadSchema]) {
+            throw new Error(`Event '${eventKey}' references payloadSchema '${eventDef.payloadSchema}' ` +
+                `which is not defined in schemas. Available schemas: ${Object.keys(def.schemas).join(', ')}`);
+        }
+    }
+    // ── Phase 6: Cross-validate schema references in functions ──
+    for (const [fnKey, fn] of Object.entries(def.functions)) {
+        if (fn.requestSchema && !def.schemas[fn.requestSchema]) {
+            throw new Error(`Function '${fnKey}' references requestSchema '${fn.requestSchema}' ` +
+                `which is not defined in schemas. Available schemas: ${Object.keys(def.schemas).join(', ')}`);
+        }
+        if (fn.responseSchema && !def.schemas[fn.responseSchema]) {
+            throw new Error(`Function '${fnKey}' references responseSchema '${fn.responseSchema}' ` +
+                `which is not defined in schemas. Available schemas: ${Object.keys(def.schemas).join(', ')}`);
+        }
+    }
+    return def;
+}

package/dist/integrationSpec.d.ts

@@ -0,0 +1,204 @@
+import { z } from "zod";
+export declare const IntegrationSpecSchema: z.ZodObject<{
+    apiVersion: z.ZodString;
+    kind: z.ZodLiteral<"Integration">;
+    metadata: z.ZodObject<{
+        slug: z.ZodString;
+        name: z.ZodString;
+        displayName: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        icon: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        logoUrl: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    spec: z.ZodObject<{
+        type: z.ZodEnum<{
+            api_key: "api_key";
+            oidc: "oidc";
+            oauth2: "oauth2";
+        }>;
+        endpoints: z.ZodOptional<z.ZodObject<{
+            authorization: z.ZodOptional<z.ZodString>;
+            token: z.ZodOptional<z.ZodString>;
+            userinfo: z.ZodOptional<z.ZodString>;
+            revocation: z.ZodOptional<z.ZodString>;
+            jwks: z.ZodOptional<z.ZodString>;
+            baseUrl: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        runtime: z.ZodObject<{
+            type: z.ZodString;
+            image: z.ZodString;
+            queue: z.ZodString;
+            port: z.ZodOptional<z.ZodNumber>;
+            command: z.ZodArray<z.ZodString>;
+            resources: z.ZodObject<{
+                cpu: z.ZodString;
+                memory: z.ZodString;
+            }, z.core.$strip>;
+            envSpec: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                value: z.ZodOptional<z.ZodString>;
+                secret: z.ZodOptional<z.ZodBoolean>;
+                default: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>;
+        actions: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            displayName: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            async: z.ZodOptional<z.ZodBoolean>;
+            input: z.ZodOptional<z.ZodUnknown>;
+            output: z.ZodOptional<z.ZodUnknown>;
+            schema: z.ZodOptional<z.ZodObject<{
+                input: z.ZodString;
+                output: z.ZodString;
+            }, z.core.$strip>>;
+            fga: z.ZodOptional<z.ZodObject<{
+                resourceType: z.ZodString;
+                relation: z.ZodString;
+            }, z.core.$strip>>;
+            capabilities: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"webhook">;
+                eventTypes: z.ZodArray<z.ZodString>;
+                source: z.ZodString;
+                endpoint: z.ZodOptional<z.ZodString>;
+                headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                authentication: z.ZodOptional<z.ZodObject<{
+                    type: z.ZodEnum<{
+                        bearer: "bearer";
+                        basic: "basic";
+                        api_key: "api_key";
+                        signature: "signature";
+                    }>;
+                    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"scheduled">;
+                cron: z.ZodString;
+                timezone: z.ZodOptional<z.ZodString>;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"queue">;
+                topics: z.ZodArray<z.ZodString>;
+                queueName: z.ZodOptional<z.ZodString>;
+                consumerGroup: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"stream">;
+                streamName: z.ZodString;
+                eventTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                consumerGroup: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>>;
+        }, z.core.$strip>>;
+        capabilities: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"webhook">;
+            eventTypes: z.ZodArray<z.ZodString>;
+            source: z.ZodString;
+            endpoint: z.ZodOptional<z.ZodString>;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            authentication: z.ZodOptional<z.ZodObject<{
+                type: z.ZodEnum<{
+                    bearer: "bearer";
+                    basic: "basic";
+                    api_key: "api_key";
+                    signature: "signature";
+                }>;
+                config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"scheduled">;
+            cron: z.ZodString;
+            timezone: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"queue">;
+            topics: z.ZodArray<z.ZodString>;
+            queueName: z.ZodOptional<z.ZodString>;
+            consumerGroup: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"stream">;
+            streamName: z.ZodString;
+            eventTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            consumerGroup: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>>;
+        schemas: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            slug: z.ZodString;
+            name: z.ZodString;
+            type: z.ZodEnum<{
+                response: "response";
+                request: "request";
+                entity: "entity";
+                webhook_payload: "webhook_payload";
+                configuration: "configuration";
+            }>;
+            description: z.ZodOptional<z.ZodString>;
+            schema: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+            version: z.ZodOptional<z.ZodString>;
+            fieldCount: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
+        events: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            slug: z.ZodString;
+            name: z.ZodString;
+            direction: z.ZodEnum<{
+                inbound: "inbound";
+                outbound: "outbound";
+                bidirectional: "bidirectional";
+            }>;
+            description: z.ZodOptional<z.ZodString>;
+            category: z.ZodOptional<z.ZodString>;
+            severity: z.ZodOptional<z.ZodEnum<{
+                error: "error";
+                info: "info";
+                warning: "warning";
+                critical: "critical";
+            }>>;
+            payloadSchema: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        functions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            slug: z.ZodString;
+            name: z.ZodString;
+            httpMethod: z.ZodEnum<{
+                GET: "GET";
+                POST: "POST";
+                PATCH: "PATCH";
+                DELETE: "DELETE";
+                PUT: "PUT";
+            }>;
+            endpointPath: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            requestSchema: z.ZodOptional<z.ZodString>;
+            responseSchema: z.ZodOptional<z.ZodString>;
+            requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            category: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+    build: z.ZodOptional<z.ZodObject<{
+        dockerfile: z.ZodString;
+        context: z.ZodString;
+    }, z.core.$strip>>;
+    ui: z.ZodOptional<z.ZodObject<{
+        category: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    fga: z.ZodOptional<z.ZodObject<{
+        types: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            relations: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
+                computedUserset: z.ZodObject<{
+                    object: z.ZodString;
+                    relation: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>]>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type IntegrationSpec = z.infer<typeof IntegrationSpecSchema>;
+/**
+ * Parse nova-integration.yaml content and validate against the IntegrationSpec schema.
+ * @param yamlContent String contents of a nova-integration.yaml specification
+ * @returns Parsed IntegrationSpec object
+ * @throws Error with validation details if parsing or validation fail
+ */
+export declare function parseIntegrationSpec(yamlContent: string): IntegrationSpec;