@newhomestar/sdk 0.5.2 → 0.6.5

package/dist/integration.d.ts

@@ -0,0 +1,398 @@
+import { z, type ZodTypeAny } from "zod";
+/** Where the parameter is sent in the HTTP request */
+export type ParamIn = 'path' | 'query' | 'body' | 'header';
+/** UI input widget type hint for the admin dashboard form builder */
+export type ParamUiType = 'text' | 'textarea' | 'number' | 'integer' | 'boolean' | 'date' | 'datetime' | 'select' | 'multiselect' | 'password' | 'email' | 'url' | 'uuid' | 'json' | 'hidden';
+/**
+ * Per-field metadata for action input parameters.
+ *
+ * Tells the platform where each field goes in the HTTP request (path, query,
+ * body, header) and what UI widget the admin dashboard should render.
+ *
+ * @example
+ * ```ts
+ * params: {
+ *   id:       { in: "path",  uiType: "text",   label: "Worker ID", required: true },
+ *   asOfDate: { in: "query", uiType: "date",   label: "As-of Date", placeholder: "YYYY-MM-DD" },
+ *   syncType: { in: "body",  uiType: "select", label: "Sync Type", options: [
+ *     { label: "Full", value: "full" },
+ *     { label: "Incremental", value: "incremental" },
+ *   ]},
+ * }
+ * ```
+ */
+export interface ParamMeta {
+    /** Where this parameter is sent: path, query, body, or header */
+    in: ParamIn;
+    /** UI widget type hint — tells the admin dashboard what input to render */
+    uiType?: ParamUiType;
+    /** Human-readable label (overrides the field name) */
+    label?: string;
+    /** Help text / description shown below the input */
+    description?: string;
+    /** Placeholder text for the input */
+    placeholder?: string;
+    /** Whether this field is required (overrides Zod's optional/required) */
+    required?: boolean;
+    /** Default value shown in the UI */
+    defaultValue?: unknown;
+    /** Options for select/multiselect UI types */
+    options?: Array<{
+        label: string;
+        value: string | number | boolean;
+    }>;
+    /** Minimum value (for number/integer) or min length (for string) */
+    min?: number;
+    /** Maximum value (for number/integer) or max length (for string) */
+    max?: number;
+    /** Step increment for number inputs (e.g., 1, 0.01) */
+    step?: number;
+    /** Regex pattern for frontend validation */
+    pattern?: string;
+    /** Display order (lower = higher priority, default = declaration order) */
+    order?: number;
+    /** Group name for visual grouping in the form (e.g., "Identity", "Options") */
+    group?: string;
+}
+export type SchemaType = 'request' | 'response' | 'entity' | 'webhook_payload' | 'configuration';
+export interface IntegrationSchemaDef<T extends ZodTypeAny = ZodTypeAny> {
+    /** Human-readable name for this schema */
+    name: string;
+    /** Unique slug within this integration (snake_case) */
+    slug: string;
+    /** Optional description */
+    description?: string;
+    /** Classification of this schema */
+    schemaType: SchemaType;
+    /** Zod schema — converted to JSON Schema during `nova integrations build` */
+    schema: T;
+    /** Developer-controlled version string (e.g., "1.0.0") */
+    version?: string;
+    /** Direct Zod reference for use in actions/events (lean API) */
+    shape?: T;
+}
+/**
+ * **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 declare function integrationSchema<T extends ZodTypeAny>(cfg: {
+    name: string;
+    slug: string;
+    description?: string;
+    schemaType: SchemaType;
+    schema: T;
+    version?: string;
+}): IntegrationSchemaDef<T>;
+/**
+ * **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 declare function schema<T extends ZodTypeAny>(schemaType: SchemaType, zodSchema: T, opts?: {
+    version?: string;
+    description?: string;
+}): IntegrationSchemaDef<T>;
+export interface IntegrationEventDef {
+    /** Unique event slug within this integration (dot-notation, e.g. "worker.hire") */
+    slug: string;
+    /** Human-readable name */
+    name: string;
+    /** Direction of the event relative to the platform */
+    direction: 'inbound' | 'outbound' | 'bidirectional';
+    /** Optional description of the event */
+    description?: string;
+    /** Event category for grouping (e.g., "lifecycle", "payroll") */
+    category?: string;
+    /** Severity/importance level */
+    severity?: 'info' | 'warning' | 'error' | 'critical';
+    /** Reference to a schema slug that defines the event payload shape */
+    payloadSchema?: string;
+}
+/**
+ * **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 declare function integrationEvent(cfg: IntegrationEventDef): IntegrationEventDef;
+/**
+ * **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 declare function event(direction: IntegrationEventDef['direction'], opts?: {
+    payload?: IntegrationSchemaDef | ZodTypeAny;
+    severity?: IntegrationEventDef['severity'];
+    category?: string;
+    description?: string;
+}): IntegrationEventDef;
+export interface IntegrationFunctionDef {
+    /** Unique function slug within this integration (snake_case) */
+    slug: string;
+    /** Human-readable name */
+    name: string;
+    /** HTTP method for the external API call */
+    httpMethod: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Endpoint path template (e.g., "/hr/v2/workers/{workerId}") */
+    endpointPath: string;
+    /** Description of what this function does */
+    description?: string;
+    /** Reference to a schema slug that defines the request body shape */
+    requestSchema?: string;
+    /** Reference to a schema slug that defines the response body shape */
+    responseSchema?: string;
+    /** OAuth scopes required to call this function */
+    requiredScopes?: string[];
+    /** Function category for grouping (e.g., "workers", "payroll") */
+    category?: string;
+    /** Capabilities metadata (e.g., "webhook", "scheduled", "queue") — can be simple strings or structured objects */
+    capabilities?: (string | Record<string, unknown>)[];
+}
+/**
+ * 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 declare function integrationFunction(cfg: IntegrationFunctionDef): IntegrationFunctionDef;
+/**
+ * Full integration definition — the single source of truth.
+ *
+ * Integrations are containerized services (like workers) that also carry
+ * structured configuration: schemas, events, and functions. When pushed
+ * via `nova integrations push`, the container image is deployed and the
+ * config is synced to the platform database.
+ */
+export interface IntegrationDef {
+    /** Unique integration slug (snake_case, e.g. "adp_workforce_now") */
+    slug: string;
+    /** Human-readable name */
+    name: string;
+    /** Short description */
+    description?: string;
+    /** Integration authentication type */
+    integrationType: 'oidc' | 'oauth2' | 'api_key';
+    /** Category for grouping (e.g., "hr", "crm", "finance") */
+    category?: string;
+    /** Logo URL for the admin dashboard */
+    logoUrl?: string;
+    /** Brand color hex code */
+    color?: string;
+    /** OAuth2/OIDC authorization endpoint */
+    authorizationEndpoint?: string;
+    /** OAuth2/OIDC token endpoint */
+    tokenEndpoint?: string;
+    /** OIDC userinfo endpoint */
+    userinfoEndpoint?: string;
+    /** OAuth2 token revocation endpoint */
+    revocationEndpoint?: string;
+    /** OIDC JWKS URI */
+    jwksUri?: string;
+    /** Base URL for API calls */
+    baseUrl?: string;
+    /** OAuth scopes to request */
+    scopes?: string[];
+    /** PGMQ queue name for async message processing */
+    queue: string;
+    /** Display name (used in admin dashboard and nova-integration.yaml) */
+    displayName?: string;
+    /** Icon URL */
+    icon?: string;
+    /** Tags for discovery/filtering */
+    tags?: string[];
+    /** UI metadata */
+    ui?: {
+        category?: string;
+        color?: string;
+    };
+    /** Resource limits for the container */
+    resources?: {
+        cpu: string;
+        memory: string;
+    };
+    /** Environment variable spec for deployment */
+    envSpec?: Array<{
+        name: string;
+        secret: boolean;
+        default?: string;
+    }>;
+    /** Map of action definitions — same as workers */
+    actions: Record<string, any>;
+    /** Schema definitions — Zod schemas converted to JSON Schema on build */
+    schemas: Record<string, IntegrationSchemaDef>;
+    /** Event definitions — describe inbound/outbound events */
+    events: Record<string, IntegrationEventDef>;
+    /** Function definitions — describe external API endpoints */
+    functions: Record<string, IntegrationFunctionDef>;
+}
+export declare const IntegrationDefSchema: z.ZodObject<{
+    slug: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    integrationType: z.ZodEnum<{
+        api_key: "api_key";
+        oidc: "oidc";
+        oauth2: "oauth2";
+    }>;
+    category: z.ZodOptional<z.ZodString>;
+    logoUrl: z.ZodOptional<z.ZodString>;
+    color: z.ZodOptional<z.ZodString>;
+    authorizationEndpoint: z.ZodOptional<z.ZodString>;
+    tokenEndpoint: z.ZodOptional<z.ZodString>;
+    userinfoEndpoint: z.ZodOptional<z.ZodString>;
+    revocationEndpoint: z.ZodOptional<z.ZodString>;
+    jwksUri: z.ZodOptional<z.ZodString>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    queue: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ui: z.ZodOptional<z.ZodObject<{
+        category: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    resources: z.ZodOptional<z.ZodObject<{
+        cpu: z.ZodString;
+        memory: z.ZodString;
+    }, z.core.$strip>>;
+    envSpec: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        secret: z.ZodBoolean;
+        default: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    actions: z.ZodRecord<z.ZodString, z.ZodAny>;
+    schemas: z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        slug: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        schemaType: z.ZodEnum<{
+            response: "response";
+            request: "request";
+            entity: "entity";
+            webhook_payload: "webhook_payload";
+            configuration: "configuration";
+        }>;
+        schema: z.ZodAny;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    events: z.ZodRecord<z.ZodString, 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.ZodRecord<z.ZodString, 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>;
+        capabilities: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Result of validating an integration definition before build/push.
+ * Errors block the operation; warnings are printed but non-blocking.
+ */
+export interface ValidationResult {
+    /** True if no errors were found (warnings are allowed) */
+    valid: boolean;
+    /** Blocking issues that must be fixed before build/push */
+    errors: string[];
+    /** Non-blocking recommendations */
+    warnings: string[];
+}
+/**
+ * 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 declare function validateIntegration(def: IntegrationDef): ValidationResult;
+export declare function defineIntegration<T extends IntegrationDef>(def: T): T;