spine-framework 0.1.61 → 1.0.0

package/dist/functions/_shared/index.d.ts

@@ -1,299 +0,0 @@
-/**
- * @module index
- * @audience installer
- * @layer shared-core
- * @stability stable
- *
- * Spine v2 Core — Public Import Surface
- *
- * This is the **single, stable entry point** for all custom code importing
- * Spine core functionality. Everything exported here is a committed contract.
- * Internal helpers not listed here are free to change without notice.
- *
- * ## Usage
- *
- * ### In custom functions (v2-custom/functions/)
- * ```ts
- * import { runPipeline, adminDb, SYSTEM_PRINCIPAL, CoreContext } from '../_shared'
- *
- * const ctx: CoreContext = {
- *   principal: SYSTEM_PRINCIPAL,
- *   accountId: myAccountId,
- *   db: adminDb,
- *   requestId: crypto.randomUUID()
- * }
- * const result = await runPipeline(pipelineId, triggerData, ctx)
- * ```
- *
- * ### In CLI commands
- * ```ts
- * import { runPipeline, adminDb, resolvePrincipal, CoreContext } from '../functions/_shared'
- * ```
- *
- * ### Stability contract
- * - All exports in this file are stable across patch and minor versions
- * - Breaking changes require a major version bump and migration guide
- * - Do NOT import from individual `_shared/*.ts` files directly — use this index
- *
- * @seeAlso middleware.ts (CoreContext, createHandler, HTTP helpers)
- * @seeAlso principal.ts (Principal interface, SYSTEM_PRINCIPAL, resolvePrincipal)
- * @seeAlso db.ts (adminDb, getUserDb, joins)
- * @seeAlso pipeline-runner.ts (runPipeline, ExecutionResult)
- * @seeAlso trigger-engine.ts (fire*Triggers, EventType)
- * @seeAlso agent-runner.ts (runAgent, AgentConfig, InferenceResult)
- * @seeAlso permissions.ts (PermissionEngine, sanitizeRecordData)
- * @seeAlso schema-utils.ts (generateValidationSchema, ValidationSchema)
- * @seeAlso audit.ts (emitAudit)
- */
-/**
- * CoreContext — the minimal execution context accepted by all Spine core functions.
- * Construct one directly for import/CLI usage; API handlers get it from createHandler().
- *
- * @example
- * ```ts
- * const ctx: CoreContext = {
- *   principal: SYSTEM_PRINCIPAL,
- *   accountId: 'uuid-here',
- *   db: adminDb,
- *   requestId: crypto.randomUUID()
- * }
- * ```
- */
-export type { CoreContext } from './middleware';
-/**
- * RequestContext — CoreContext extended with HTTP-specific fields.
- * Only needed if you are writing an API handler function.
- */
-export type { RequestContext, HandlerFunction, HandlerResult } from './middleware';
-/**
- * createHandler — wraps a handler function with auth, principal resolution, and audit.
- * Use this when writing Netlify function handlers.
- */
-export { createHandler, requireUserContext, requireSystemContextWithAudit, json, error as errorResponse, cors } from './middleware';
-/**
- * Principal — unified identity for all actors (humans, machines, cron, triggers).
- */
-export type { Principal } from './principal';
-/**
- * resolvePrincipal — resolves a Principal from an incoming HTTP event.
- * Used in custom handler wrappers.
- */
-export { resolvePrincipal } from './principal';
-/**
- * isSystemAdmin — returns true if principal has the system_admin role.
- */
-export { isSystemAdmin } from './principal';
-/**
- * machineHasScope — checks whether a machine principal has a given scope.
- * Supports wildcards: "items:*", "*:*".
- */
-export { machineHasScope, humanHasRole } from './principal';
-/**
- * getPrincipalDb — returns the appropriate DB client for a principal.
- * Humans get RLS-scoped client; machines get adminDb.
- */
-export { getPrincipalDb } from './principal';
-/**
- * formatPrincipalForAudit — structures a principal for audit log metadata.
- */
-export { formatPrincipalForAudit } from './principal';
-/**
- * ANONYMOUS_PRINCIPAL — static principal for unauthenticated requests.
- */
-export { ANONYMOUS_PRINCIPAL } from './principal';
-/**
- * SYSTEM_PRINCIPAL — static principal for internal system operations.
- * Use this when constructing a CoreContext for CLI or import usage without
- * a real authenticated user.
- */
-export { SYSTEM_PRINCIPAL } from './principal';
-/**
- * adminDb — Supabase service_role client. Bypasses RLS.
- * Use for system operations, migrations, machine principal actions.
- */
-export { adminDb } from './db';
-/**
- * getUserDb — Returns a JWT-scoped Supabase client with RLS enforced.
- * Use for human-principal requests.
- */
-export { getUserDb } from './db';
-/**
- * joins — PostgREST relationship hint strings for common FK relationships.
- * @example `.select(\`*, \${joins.type}, \${joins.app}\`)`
- */
-export { joins } from './db';
-export type { DbResult } from './db';
-/**
- * runPipeline — execute a pipeline by ID with trigger data.
- *
- * @param pipelineId - UUID of the pipeline to run
- * @param triggerData - Arbitrary data passed to all pipeline stages
- * @param ctx - CoreContext (principal + accountId + db + requestId)
- * @returns ExecutionResult with per-stage output and final status
- * @throws If pipeline not found or inactive
- *
- * @example API handler
- * ```ts
- * const result = await runPipeline(body.pipeline_id, body.data, ctx)
- * ```
- *
- * @example Custom import
- * ```ts
- * import { runPipeline, adminDb, SYSTEM_PRINCIPAL } from '../_shared'
- * const ctx = { principal: SYSTEM_PRINCIPAL, accountId, db: adminDb, requestId: crypto.randomUUID() }
- * const result = await runPipeline('uuid', { item_id: '...' }, ctx)
- * ```
- *
- * @example CLI
- * ```bash
- * spine pipelines run <pipeline-id> --data '{"item_id":"..."}'
- * ```
- */
-export { runPipeline } from './pipeline-runner';
-export type { ExecutionResult, StageResult } from './pipeline-runner';
-/**
- * checkAndFireTriggers — evaluate and fire all active triggers matching an event.
- *
- * @param eventType - e.g. 'item_created', 'account_updated'
- * @param entityType - table name string
- * @param entityId - UUID of the affected entity
- * @param entityData - full entity data for condition evaluation
- * @param ctx - CoreContext
- *
- * @example
- * ```ts
- * await checkAndFireTriggers('item_created', 'items', item.id, item, ctx)
- * ```
- */
-export { checkAndFireTriggers, fireCreateTriggers, fireUpdateTriggers, fireDeleteTriggers } from './trigger-engine';
-export type { EventType } from './trigger-engine';
-/**
- * runAgent — run AI agent inference for a user message in a thread.
- *
- * Resolves agent config from thread → agent → prompt_config chain,
- * assembles RAG context, calls LLM, handles tool dispatch and escalation.
- *
- * @param threadId - UUID of the thread
- * @param userMessage - The user's message text
- * @param ctx - CoreContext
- * @returns Saved agent message record
- *
- * @example
- * ```ts
- * const msg = await runAgent(threadId, 'How do I reset my password?', ctx)
- * ```
- */
-export { runAgent, resolveAgentConfig } from './agent-runner';
-export type { AgentConfig, InferenceResult, ToolCall, ToolResult } from './agent-runner';
-/**
- * PermissionEngine — the single source of truth for all authorization.
- *
- * @example
- * ```ts
- * const canRead = await PermissionEngine.canAccessRecord(ctx, record, 'read')
- * const sanitized = await PermissionEngine.sanitizeRecordData(ctx, record, 'support_ticket')
- * ```
- */
-export { PermissionEngine } from './permissions';
-export type { PermissionResult } from './permissions';
-export { sanitizeRecordData, validateUpdatePermissions, canAccessRecord } from './permissions';
-/**
- * generateValidationSchema — derive a structural validation schema from a design schema.
- * Called automatically on type create/update; also useful in custom code.
- */
-export { generateValidationSchema } from './schema-utils';
-export type { ValidationSchema } from './schema-utils';
-/**
- * emitAudit — emit a structured audit log entry with full principal provenance.
- *
- * @param ctx - CoreContext
- * @param action - e.g. 'items.create', 'pipeline.completed'
- * @param target - { type, id, account_id }
- * @param metadata - additional structured context
- *
- * @example
- * ```ts
- * await emitAudit(ctx, 'deal.stage_changed', { type: 'items', id: deal.id }, {
- *   before: { stage: 'prospect' },
- *   after: { stage: 'qualified' }
- * })
- * ```
- */
-export { emitAudit } from './audit';
-/**
- * resolveHandler — dynamically load a webhook handler by name.
- *
- * Used by integration-routes.ts to resolve handlers at runtime
- * without static imports, enabling custom handlers to self-register.
- *
- * @param handlerName — The handler identifier from webhook_handlers table
- * @returns Handler function or null if not found
- *
- * @example
- * ```ts
- * const handler = await resolveHandler('cortex-webhook')
- * if (handler) await handler(event, context)
- * ```
- */
-export { resolveHandler, lookupHandler, loadHandler } from './webhook-registry';
-/**
- * registerWebhookHandler — self-register a custom webhook handler.
- *
- * Use in custom Netlify functions to register as webhook handlers
- * without modifying core code.
- *
- * @param config — Handler registration details
- *
- * @example
- * ```ts
- * import { registerWebhookHandler } from '@core/_shared'
- * import { adminDb } from '@core/_shared'
- *
- * registerWebhookHandler({
- *   name: 'my-handler',
- *   functionName: 'custom_my-handler',
- *   events: ['item.created']
- * }, adminDb)
- * ```
- */
-export { registerWebhookHandler, deregisterWebhookHandler, isHandlerRegistered } from './webhook-registration';
-export type { WebhookHandlerRegistration } from './webhook-registration';
-/**
- * loadManifest — load and parse an app manifest.json file.
- *
- * Used by apps.ts to merge database records with file-based
- * app configuration (name, routes, nav_items, required_roles).
- *
- * @param manifestPath — Path to manifest.json relative to project root
- * @returns Parsed AppManifest or null if not found/invalid
- *
- * @example
- * ```ts
- * const manifest = loadManifest('custom/apps/cortex/manifest.json')
- * console.log(manifest.required_roles) // ['member']
- * ```
- */
-export { loadManifest, mergeWithManifest, clearManifestCache, discoverManifests } from './app-manifest';
-export type { AppManifest, NavItem } from './app-manifest';
-/**
- * Testing utilities for custom code developers.
- *
- * Use these helpers to test your custom functions without
- * full deployment. Includes mock contexts, principals, and
- * assertion helpers.
- *
- * @example
- * ```ts
- * import { makeTestContext, mockPrincipal, cleanup } from '@core/testing'
- *
- * describe('My Handler', () => {
- *   const ctx = makeTestContext({
- *     principal: mockPrincipal({ roles: ['member'] })
- *   })
- * })
- * ```
- */
-export { makeTestContext, mockPrincipal, mockLogger, mockEvent, mockNetlifyContext, cleanup, setupTests, expectSuccessResponse, expectErrorResponse } from './testing';
-export type { TestContext, TestPrincipal, TestLogger } from './testing';
-export { resolveTypeIds, resolveTypeId, resolveLinkTypeIds, resolveAccountId, resolveAgentId, resolvePromptConfigId } from './resolve-ids';
-//# sourceMappingURL=index.d.ts.map

package/dist/functions/_shared/index.d.ts.map

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

package/dist/functions/_shared/middleware.d.ts

@@ -1,315 +0,0 @@
-/**
- * @module middleware
- * @audience both
- * @layer shared-core
- * @stability stable
- *
- * HTTP handler factory and request context types for all Spine Netlify functions.
- * This module owns the boundary between raw HTTP events and the typed execution
- * context (`RequestContext`) used by every handler. It also provides guard
- * utilities (`requireUserContext`, `requireSystemContextWithAudit`) used to
- * enforce authentication at the top of handlers.
- *
- * The key invariant: `createHandler` always resolves a `Principal` via
- * `resolvePrincipal` before calling the inner handler. Handlers never receive
- * an unauthenticated context — anonymous requests are rejected at the wrapper.
- *
- * IMPORTANT: `result.data` is never unwrapped in `createHandler`. Handlers
- * return records directly. Unwrapping would collide with records that have a
- * `.data` JSONB column.
- *
- * @seeAlso principal.ts (resolvePrincipal, getPrincipalDb, isSystemAdmin)
- * @seeAlso audit.ts (emitAudit — called after every successful handler)
- * @seeAlso db.ts (adminDb, getUserDb — selected by getPrincipalDb)
- * @seeAlso index.ts (re-exports CoreContext, createHandler, requireUserContext)
- */
-import { Principal } from './principal';
-/**
- * Minimal execution context passed to all Spine core functions.
- *
- * This is the canonical context for `pipeline-runner`, `trigger-engine`,
- * `agent-runner`, `audit`, and any custom code in `v2-custom/`. It contains
- * only what core logic needs: identity, account scope, and a DB client.
- *
- * `RequestContext` (used inside HTTP handlers) extends this with HTTP-specific
- * fields (`appId`, `query`). Direct importers and CLI callers construct
- * `CoreContext` directly without going through `createHandler`.
- *
- * @inputSpec principal: Principal — must be a resolved principal (not null)
- * @inputSpec accountId: string | null — null is allowed for system-level ops only
- * @inputSpec db: SupabaseClient — use adminDb for system ops, getUserDb for RLS
- * @inputSpec requestId: string — UUID; ties execution to audit log entries
- * @calledBy pipeline-runner.ts, trigger-engine.ts, agent-runner.ts, audit.ts,
- *   tests/integration/helpers.ts (makeTestCtx), cli/context.ts
- *
- * @example Import usage (v2-custom/)
- * ```ts
- * import { CoreContext, adminDb, SYSTEM_PRINCIPAL } from '../_shared/index'
- * const ctx: CoreContext = {
- *   principal: SYSTEM_PRINCIPAL,
- *   accountId: 'uuid-of-account',
- *   db: adminDb,
- *   requestId: crypto.randomUUID()
- * }
- * await runPipeline(pipelineId, data, ctx)
- * ```
- *
- * @example CLI usage
- * ```bash
- * # CLI constructs CoreContext from .xenv credentials automatically
- * spine pipelines run <pipeline-id>
- * ```
- */
-export interface CoreContext {
-    /** Resolved principal for this execution */
-    principal: Principal;
-    /** Primary account scope — null for system-level operations */
-    accountId: string | null;
-    /** Database client — use adminDb for system ops, getUserDb for RLS-scoped */
-    db: any;
-    /** Unique ID for this execution (used in audit logs) */
-    requestId: string;
-}
-/**
- * HTTP-layer execution context — extends `CoreContext` with request-specific fields.
- *
- * Constructed inside `createHandler` after principal resolution. Not used by
- * core logic directly — core functions accept `CoreContext`. The extra fields
- * are available to handlers that need them (e.g., `query.action`, `appId`).
- *
- * @inputSpec appId: string | null — from `x-app-id` header; null if absent
- * @inputSpec query: Record<string, string> — parsed queryStringParameters from event
- * @calledBy All 19 API handler functions (as the first argument)
- * @seeAlso CoreContext (parent interface)
- */
-export interface RequestContext extends CoreContext {
-    /** App ID from `x-app-id` header — used for app-scoped operations */
-    appId: string | null;
-    /** Parsed query string parameters from the Netlify event */
-    query: Record<string, string>;
-    /** Request path from the Netlify event */
-    requestPath: string;
-}
-/**
- * Signature for all Spine HTTP handler functions.
- *
- * Every handler file exports a default that calls `createHandler(myHandler)`.
- * The `body` parameter is the parsed JSON body, or null for GET requests.
- *
- * @inputSpec ctx: RequestContext — fully resolved context; never null
- * @inputSpec body: any — parsed JSON body or null; undefined for GET requests
- * @outputSpec Promise<any> — return value is wrapped in `{ data: result }` by createHandler
- */
-export type HandlerFunction = (ctx: RequestContext, body?: any) => Promise<any>;
-/**
- * Standard envelope shape returned by `createHandler` to the HTTP client.
- *
- * On success: `{ data: <handler result>, error: null, meta: { requestId, duration } }`
- * On error: `{ data: null, error: <message> }` with appropriate HTTP status code.
- *
- * @outputSpec data: any — handler return value, never unwrapped
- * @outputSpec error: string | undefined — error message; present only on failure
- * @outputSpec meta: object | undefined — requestId + duration on success
- */
-export interface HandlerResult {
-    data?: any;
-    error?: string;
-    meta?: any;
-}
-/**
- * Wraps a handler function with principal resolution, request parsing, audit
- * logging, and error handling. This is the entry point for every Netlify function.
- *
- * Execution flow:
- *   1. Detect nested calls (event already has requestId + principal) → pass through
- *   2. Generate `requestId`, parse headers, query params
- *   3. Call `resolvePrincipal(event)` → reject anonymous with 401
- *   4. Call `getPrincipalDb(principal)` → select correct DB client
- *   5. Build `RequestContext`, parse + merge body
- *   6. Call inner handler, measure duration
- *   7. Emit `request.<method>` audit log (account-scoped requests only)
- *   8. Return `json({ data: result, error: null, meta })` envelope
- *   9. On any thrown error → return `error(message, 500)`
- *
- * @param handler - The inner handler function implementing the route logic
- * @returns Netlify-compatible async function `(event, context) => Response`
- * @throws never — all errors are caught and returned as HTTP 500
- * @inputSpec handler: HandlerFunction — must return a Promise
- * @outputSpec Netlify Lambda response object with statusCode, headers, body
- * @sideEffects DB read: principal resolution (people, api_keys tables)
- * @sideEffects DB write: emitAudit to logs table (account-scoped requests only)
- * @calledBy Every function in functions/*.ts as the default export wrapper
- * @calls resolvePrincipal, getPrincipalDb, emitAudit, json, error
- * @testIntegration tests/integration/admin-data-accounts.test.ts
- *
- * @example API handler file pattern
- * ```ts
- * import { createHandler, RequestContext } from './_shared/middleware'
- * export const handler = createHandler(async (ctx: RequestContext, body) => {
- *   const action = ctx.query.action || 'list'
- *   if (action === 'list') return listItems(ctx)
- *   throw new Error(`Unknown action: ${action}`)
- * })
- * ```
- */
-export declare function createHandler(handler: HandlerFunction): (event: any, context: any) => Promise<any>;
-/**
- * Builds a JSON HTTP response object compatible with Netlify Functions.
- *
- * Always includes CORS headers permitting requests from any origin. Used
- * internally by `createHandler` and directly by handlers that need a custom
- * status code (e.g., 201 Created).
- *
- * @param data - Any JSON-serializable value to include as the response body
- * @param status - HTTP status code (default: 200)
- * @returns Netlify Lambda response object
- * @throws never
- * @inputSpec data: any — must be JSON-serializable; circular refs will throw at stringify
- * @inputSpec status: number — valid HTTP status code (default 200)
- * @outputSpec { statusCode, headers, body: string } — body is JSON.stringify(data)
- * @sideEffects none
- * @calledBy createHandler, error, cors, and directly by some handlers
- * @testUnit none — trivial; verified by integration tests on every request
- */
-export declare function json(data: any, status?: number): {
-    statusCode: number;
-    headers: {
-        'Content-Type': string;
-        'Access-Control-Allow-Origin': string;
-        'Access-Control-Allow-Headers': string;
-        'Access-Control-Allow-Methods': string;
-    };
-    body: string;
-};
-/**
- * Builds a JSON error response with `{ data: null, error: message }` shape.
- *
- * Use this to return structured error responses from handlers. The message
- * is safe to surface to clients — do not pass internal error details.
- *
- * @param message - Human-readable error message safe to return to client
- * @param status - HTTP status code (default: 400)
- * @returns Netlify Lambda response object
- * @throws never
- * @inputSpec message: string — client-safe error description
- * @inputSpec status: number — HTTP status code (400, 401, 403, 404, 500)
- * @outputSpec { statusCode: status, body: '{"data":null,"error":"<message>"}' }
- * @sideEffects none
- * @calledBy createHandler (on caught errors), requireUserContext,
- *   requireSystemContextWithAudit, and many individual handlers
- */
-export declare function error(message: string, status?: number): {
-    statusCode: number;
-    headers: {
-        'Content-Type': string;
-        'Access-Control-Allow-Origin': string;
-        'Access-Control-Allow-Headers': string;
-        'Access-Control-Allow-Methods': string;
-    };
-    body: string;
-};
-/**
- * Parses the JSON body from a Netlify event object.
- *
- * Returns `null` if there is no body. Throws a descriptive error on malformed
- * JSON so the error surfaces cleanly from `createHandler`'s catch block.
- *
- * @param event - Raw Netlify event object
- * @returns Parsed body object or null
- * @throws Error('Invalid JSON in request body') — when body is present but not valid JSON
- * @inputSpec event.body: string | null | undefined — raw JSON string from HTTP request
- * @outputSpec any — parsed JSON object, or null if no body
- * @sideEffects none
- * @calledBy Handlers that need body outside of createHandler's automatic parsing
- */
-export declare function parseBody(event: any): any;
-/**
- * Overloaded guard that requires a resolved human principal with an account scope.
- *
- * **Overload 1 — wrapper:** wrap a handler to enforce auth before it runs.
- * **Overload 2 — inline:** call with `ctx` directly; returns an error response
- *   object if auth is missing, or `null` if auth is present (allowing the
- *   caller to do `const authErr = requireUserContext(ctx); if (authErr) return authErr`).
- *
- * Rejects requests where:
- *   - `ctx.principal` is absent
- *   - `ctx.principal.id === 'anonymous'`
- *   - `ctx.accountId` is null or empty (machine principals without an account)
- *
- * @inputSpec ctx or handler: RequestContext or HandlerFunction
- * @outputSpec HandlerFunction (overload 1) or HandlerResult | null (overload 2)
- * @throws Error('User context required') — in wrapper mode if not authenticated
- * @sideEffects none
- * @calledBy API handlers that require an authenticated human with account scope
- * @testIntegration tests/integration/isolation.test.ts
- *
- * @example Inline guard pattern (preferred)
- * ```ts
- * const authErr = requireUserContext(ctx)
- * if (authErr) return authErr
- * // ctx.principal and ctx.accountId are guaranteed non-null below here
- * ```
- *
- * @example Wrapper pattern
- * ```ts
- * export const handler = createHandler(requireUserContext(async (ctx, body) => {
- *   return listItems(ctx)
- * }))
- * ```
- */
-export declare function requireUserContext(handler: HandlerFunction): HandlerFunction;
-export declare function requireUserContext(ctx: RequestContext): HandlerResult | null;
-/**
- * Overloaded guard that requires a `system_admin` principal.
- *
- * **Overload 1 — wrapper:** wrap a handler; throws if not system_admin.
- * **Overload 2 — inline:** call with `ctx`; returns error response or null.
- *   Also accepts an optional `triggeredBy` string to set on the context for
- *   audit trail chaining (e.g. pipeline execution ID).
- *
- * Rejects requests where:
- *   - `ctx.principal` is absent or anonymous
- *   - `ctx.principal` does not have the `system_admin` role
- *
- * @param arg - Handler to wrap, or RequestContext to validate inline
- * @param triggeredBy - Optional: ID of the triggering entity (set on ctx)
- * @returns HandlerFunction (overload 1) or HandlerResult | null (overload 2)
- * @throws Error('System context required') — in wrapper mode if not system_admin
- * @inputSpec ctx.principal.roles: string[] — must include 'system_admin'
- * @outputSpec HandlerFunction | HandlerResult | null
- * @sideEffects sets `ctx.triggeredBy` when validation passes (inline mode)
- * @calledBy system-cron.ts, pipeline-executions.ts, and admin-only handlers
- * @testIntegration tests/integration/isolation.test.ts
- *
- * @example Inline guard pattern
- * ```ts
- * const authErr = requireSystemContextWithAudit(ctx, 'cron-job-id')
- * if (authErr) return authErr
- * ```
- */
-export declare function requireSystemContextWithAudit(handler: HandlerFunction): HandlerFunction;
-export declare function requireSystemContextWithAudit(ctx: RequestContext, triggeredBy?: string): HandlerResult | null;
-/**
- * Returns a 200 JSON response for CORS preflight requests.
- *
- * Netlify automatically handles OPTIONS at the CDN level for most routes, but
- * handlers that need to explicitly handle OPTIONS can call this.
- *
- * @returns json({ message: 'CORS enabled' }, 200) with CORS headers
- * @throws never
- * @inputSpec none
- * @outputSpec Netlify Lambda response with CORS headers
- * @sideEffects none
- * @calledBy Handler files that explicitly handle OPTIONS method
- */
-export declare function cors(): {
-    statusCode: number;
-    headers: {
-        'Content-Type': string;
-        'Access-Control-Allow-Origin': string;
-        'Access-Control-Allow-Headers': string;
-        'Access-Control-Allow-Methods': string;
-    };
-    body: string;
-};
-//# sourceMappingURL=middleware.d.ts.map

package/dist/functions/_shared/middleware.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../../.framework/functions/_shared/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EACL,SAAS,EAIV,MAAM,aAAa,CAAA;AAKpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,SAAS,EAAE,SAAS,CAAA;IACpB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,6EAA6E;IAC7E,EAAE,EAAE,GAAG,CAAA;IACP,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,qEAAqE;IACrE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;AAE/E;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,GAAG,CAAA;IACV,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,GAAG,CAAA;CACX;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,WAC/B,GAAG,WAAW,GAAG,kBAuGvC;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,GAAE,MAAY;;;;;;;;;EAWnD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAY;;;;;;;;;EAK1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG,CAQzC;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAAA;AAC7E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,aAAa,GAAG,IAAI,CAAA;AAmB7E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAAA;AACxF,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,cAAc,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAAA;AAgC9G;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI;;;;;;;;;EAEnB"}