@superpanel-sdk/runtime 0.2.3 → 0.5.0

package/dist/core/functions/events.d.ts

@@ -0,0 +1,247 @@
+import { z } from 'zod';
+import type { CaseInput } from '../case-orchestrator/types.js';
+import type { PageTablesDesc } from '../page/typed.js';
+import type { FunctionCtx, FunctionKind } from './types.js';
+import type { ExchangeRef } from '../context/exchanges.js';
+/**
+ * Platform events.
+ *
+ * The event name is the key of the company `events` export. For every event the
+ * platform fixes the payload, the return type (`void` for every event except
+ * `webhook.received`, which returns a {@link WebhookOutcome}) and whether the
+ * handler receives `c` — companies only choose which events to subscribe to.
+ *
+ * A handler is the company's own code, not the conversation: it does not get the page. `c` is the
+ * case ({@link CaseInput}: the instance and its business root's id, as the Orchestrator gets it); it
+ * reads and writes with `ctx.api.db`. Only `webhook.received` has no `c`: it runs before a case is known.
+ *
+ * Payloads are provider-neutral on purpose: Twilio / Gmail vocabulary is
+ * translated in the channel adapter, never carried into these types.
+ */
+/** Shared by every call event. `id` can be passed directly to `ctx.api.call.get`. */
+export type CallEventBase = {
+    id: string;
+    /** Provider-neutral name for the channel-native id (voice: Twilio CallSid). */
+    externalId: string;
+    fromNumber: string;
+    toNumber: string;
+};
+export type CallInboundEvent = CallEventBase & {
+    startedAt: string;
+};
+export type CallOutboundEvent = CallEventBase & {
+    startedAt: string;
+};
+export type CallEndedEvent = CallEventBase & {
+    /** Provider-neutral terminal outcome. */
+    outcome: 'completed' | 'busy' | 'failed' | 'no-answer' | 'canceled';
+    durationSec: number | null;
+};
+/** Shared by every SMS event. `id` can be passed directly to `ctx.api.sms.get`. */
+export type SmsEventBase = {
+    id: string;
+    fromNumber: string;
+    toNumber: string;
+    body: string;
+};
+export type SmsReceivedEvent = SmsEventBase & {
+    receivedAt: string;
+};
+export type SmsSendRequestedEvent = SmsEventBase & {
+    requestedAt: string;
+};
+/** Shared by every email event. `id` can be passed directly to `ctx.api.email.get`. */
+export type EmailEventBase = {
+    id: string;
+    /** The provider's thread id (null for a thread we start, until its first email went). */
+    threadId: string | null;
+    fromAddress: string;
+    toAddresses: string[];
+    subject: string | null;
+    body: string | null;
+};
+export type EmailReceivedEvent = EmailEventBase & {
+    receivedAt: string;
+};
+export type EmailSendRequestedEvent = EmailEventBase & {
+    requestedAt: string;
+};
+/** Events that carry no payload yet: the handler reads what it needs from `c` and `ctx.api.db`. */
+export type EmptyEvent = Record<string, never>;
+/**
+ * The HTTP request exactly as the gateway saw it. The platform verifies nothing: every header,
+ * the absolute URL and the raw body are forwarded so the handler can check the sender's signature.
+ */
+export type WebhookRequest = {
+    method: 'GET' | 'POST' | 'PUT';
+    /** Absolute URL as the sender saw it (`https://…/webhook/e/<code>/lead/created?x=1`); signatures are usually computed over it. */
+    url: string;
+    /** Sub-path after the webhook code: `/webhook/e/<code>/lead/created` → `lead/created`; `''` when absent. */
+    path: string;
+    query: Record<string, string>;
+    /** Every request header, lower-cased names, multi-valued headers joined with `, `. Nothing is removed. */
+    headers: Record<string, string>;
+    contentType: string | null;
+    /** Raw body text, always present (empty string for GET). */
+    body: string;
+};
+/**
+ * One inbound request to one of the environment's webhook URLs (made on the Webhooks page). The
+ * platform routes, stores and forwards it; it does not verify it and knows nothing
+ * about the sender's event model. The company's `webhook.ts` decides whether the request is genuine
+ * and answers with a {@link WebhookOutcome} (22-sequence-as-business-unit §9).
+ */
+export type WebhookEvent = {
+    /** Delivery id. Stable across retries: use it as an idempotency key and to find the row in Trigger history. */
+    id: string;
+    receivedAt: string;
+    /** 1 on the first run, higher on worker retries. */
+    attempt: number;
+    /**
+     * Which webhook URL received it: `name` is the URL's name on the Webhooks page (the same in test and
+     * prod).
+     */
+    webhook: {
+        id: string;
+        name: string;
+    };
+    /**
+     * Body parsed by Content-Type: JSON → the parsed value (object, array or scalar);
+     * form-urlencoded → flat object; anything else → null. `request.body` always has the raw text.
+     */
+    payload: unknown;
+    request: WebhookRequest;
+};
+/**
+ * What `webhook.received` must return. Explicit on purpose: a plain `return` is a type error.
+ * - `accepted`: the request was genuine and handled; the delivery is marked succeeded.
+ * - `rejected`: the handler's own verification failed (bad signature, unknown sender, …); the
+ *   delivery is marked rejected with `reason` and is never retried.
+ * Throwing means "something went wrong on our side": the delivery is marked failed and retried.
+ */
+export type WebhookOutcome = {
+    status: 'accepted';
+} | {
+    status: 'rejected';
+    reason: string;
+};
+/** Wire schema of {@link WebhookOutcome}; the worker validates the handler's return with it. */
+export declare const webhookOutcome: z.ZodType<WebhookOutcome>;
+/**
+ * A text or email conversation needs a person (20 §5.7, 24 §5.3): the AI marked it stuck, or its run
+ * failed; nothing was sent for what the customer wrote. The company decides who is told and how (a
+ * task, a message to the team, a field on the case).
+ */
+export type ConversationHandoffEvent = {
+    /** A call only when its model failed and the call was ended (25 §12); a stuck call reads `session.stuck`. */
+    channel: 'call' | 'sms' | 'email';
+    /** The exchange waiting for a person: the call, the text line, the email thread (21 §11.4). */
+    exchange: ExchangeRef;
+    /** The run that stopped. */
+    runId: string;
+    contactId: string;
+    /** Why: the AI marked the conversation stuck, or the run failed. */
+    cause: 'stuck' | 'error';
+    /** What went wrong, when the run failed. */
+    error?: string;
+    /** What the customer sent that is waiting for an answer. */
+    waiting: string;
+    at: string;
+};
+/** Event name → { whether the handler gets `c`, payload, handler return }. */
+export type SystemEventMap = {
+    'call.inbound': {
+        case: true;
+        event: CallInboundEvent;
+        result: void;
+    };
+    'call.outbound': {
+        case: true;
+        event: CallOutboundEvent;
+        result: void;
+    };
+    'call.ended': {
+        case: true;
+        event: CallEndedEvent;
+        result: void;
+    };
+    'sms.received': {
+        case: true;
+        event: SmsReceivedEvent;
+        result: void;
+    };
+    'sms.send-requested': {
+        case: true;
+        event: SmsSendRequestedEvent;
+        result: void;
+    };
+    'email.received': {
+        case: true;
+        event: EmailReceivedEvent;
+        result: void;
+    };
+    'email.send-requested': {
+        case: true;
+        event: EmailSendRequestedEvent;
+        result: void;
+    };
+    /** A conversation needs a person (20 §5.7): a text or email stuck or failed, a call whose model failed (25 §12). */
+    'conversation.handoff': {
+        case: true;
+        event: ConversationHandoffEvent;
+        result: void;
+    };
+    /**
+     * Reserved and unused: the platform does not send it yet (the Orchestrator hands a run to the next
+     * sequence with `scheduleNextSequence`).
+     */
+    'sequence.next': {
+        case: true;
+        event: EmptyEvent;
+        result: void;
+    };
+};
+export type SystemEventName = keyof SystemEventMap;
+export type SystemEventPayload<K extends SystemEventName> = SystemEventMap[K]['event'];
+export type SystemEventResult<K extends SystemEventName> = SystemEventMap[K]['result'];
+/**
+ * Runtime table mirroring {@link SystemEventMap}. The build uses it to pick the
+ * registry kind of each handler; the dispatcher uses it to pick the invocation path.
+ */
+export declare const SYSTEM_EVENTS: {
+    readonly [K in SystemEventName]: {
+        readonly case: SystemEventMap[K]['case'];
+    };
+};
+export declare const SYSTEM_EVENT_NAMES: readonly SystemEventName[];
+export declare function isSystemEventName(value: string): value is SystemEventName;
+/** Registry kind of an event handler: fixed per event by {@link SYSTEM_EVENTS}. */
+export declare function systemEventKind(name: SystemEventName): Extract<FunctionKind, 'case' | 'noCase'>;
+export type EventHandlerParams<K extends SystemEventName> = {
+    event: SystemEventPayload<K>;
+};
+/**
+ * Handler signature for one event; whether it gets `c` (the case) and the return type come from the
+ * event table. Like any function, a handler reads and writes with `ctx.api.db`, typed by the sequence's
+ * `PageTables` (`D`).
+ */
+export type EventHandler<C, K extends SystemEventName, D extends PageTablesDesc | undefined = undefined> = SystemEventMap[K]['case'] extends true ? (c: C, ctx: FunctionCtx<EventHandlerParams<K>, D>) => Promise<SystemEventResult<K>> : (ctx: FunctionCtx<EventHandlerParams<K>, D>) => Promise<SystemEventResult<K>>;
+/** Company `events` export: subscribe to any subset of platform events. */
+export type EventHandlers<C = CaseInput, D extends PageTablesDesc | undefined = undefined> = {
+    [K in SystemEventName]?: EventHandler<C, K, D>;
+};
+/** Loader/host-side view of an events map: handler `c` and `ctx` types are not known. */
+export type AnyEventHandlers = {
+    [K in SystemEventName]?: (...args: any[]) => Promise<unknown>;
+};
+/** The company function that receives webhooks: `received` of `webhook.ts` at the repository root. */
+export declare const WEBHOOK_RECEIVED_FUNCTION = "webhook.received";
+/**
+ * `received` of `webhook.ts` (22 §9): every webhook of the environment comes here, told apart by
+ * `event.webhook.name`. It runs with no sequence; to hand a request to one, start an instance or call
+ * its code through the platform API. Return accepted / rejected explicitly; throw to be retried.
+ */
+export type WebhookHandler<D extends PageTablesDesc | undefined = undefined> = (ctx: FunctionCtx<{
+    event: WebhookEvent;
+}, D>) => Promise<WebhookOutcome>;
+//# sourceMappingURL=events.d.ts.map

package/dist/core/functions/events.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+/** Wire schema of {@link WebhookOutcome}; the worker validates the handler's return with it. */
+export const webhookOutcome = z.discriminatedUnion('status', [
+    z.object({ status: z.literal('accepted') }),
+    z.object({ status: z.literal('rejected'), reason: z.string() }),
+]);
+/**
+ * Runtime table mirroring {@link SystemEventMap}. The build uses it to pick the
+ * registry kind of each handler; the dispatcher uses it to pick the invocation path.
+ */
+export const SYSTEM_EVENTS = {
+    'call.inbound': { case: true },
+    'call.outbound': { case: true },
+    'call.ended': { case: true },
+    'sms.received': { case: true },
+    'sms.send-requested': { case: true },
+    'email.received': { case: true },
+    'email.send-requested': { case: true },
+    'conversation.handoff': { case: true },
+    'sequence.next': { case: true },
+};
+export const SYSTEM_EVENT_NAMES = Object.keys(SYSTEM_EVENTS);
+export function isSystemEventName(value) {
+    return Object.hasOwn(SYSTEM_EVENTS, value);
+}
+/** Registry kind of an event handler: fixed per event by {@link SYSTEM_EVENTS}. */
+export function systemEventKind(name) {
+    return SYSTEM_EVENTS[name].case ? 'case' : 'noCase';
+}
+/** The company function that receives webhooks: `received` of `webhook.ts` at the repository root. */
+export const WEBHOOK_RECEIVED_FUNCTION = 'webhook.received';
+//# sourceMappingURL=events.js.map

package/dist/core/functions/func-ref.d.ts

@@ -1,4 +1,4 @@
-import type { DefinedFunc, FuncMap } from './types.js';
+import type { DefinedFunc, FuncMap, FunctionKind } from './types.js';
 /**
  * Author-time function reference:
  * - string key: `'computeIsQualified'`
@@ -7,10 +7,19 @@ import type { DefinedFunc, FuncMap } from './types.js';
  * Compiled / runtime schemas always store the string name.
  */
 export type FuncRef = string | DefinedFunc;
+/**
+ * Structural stand-in for narrowed refs such as `DefinedCaseFunc<never, …>`: a function whose
+ * `caseContext` is typed `never` is not assignable to `DefinedFunc<any>` (any → never fails),
+ * but identity lookup only needs the object.
+ */
+export type FuncRefLike = FuncRef | {
+    kind: FunctionKind;
+    main: unknown;
+};
 /**
  * Normalize a {@link FuncRef} to the functions-map key.
  * Object refs need the same `functions` map for identity lookup
  * (plain map values do not carry `name`).
  */
-export declare function resolveFuncName(ref: FuncRef, functions?: FuncMap): string;
+export declare function resolveFuncName(ref: FuncRefLike, functions?: FuncMap): string;
 //# sourceMappingURL=func-ref.d.ts.map

package/dist/core/functions/schedules.d.ts

@@ -0,0 +1,51 @@
+import type { PageTablesDesc } from '../page/typed.js';
+import type { FunctionCtx } from './types.js';
+/**
+ * Recurring jobs (25 §6.4): `schedules.ts` at the repository root (company level, next to
+ * `webhook.ts`) or in `sequences/<id>/` (sequence level). Each runs on its cron in every environment
+ * whose live release has it, with no case and no contact; `ctx.api` is the webhook handler's
+ * (`db`, `integration`, `instances.start`, `instances.notify`, `log`, `kv`).
+ */
+/** What `ctx.params.schedule` tells a run: which job, and the tick it runs for. */
+export type ScheduleTick = {
+    /** The job's key in `defineSchedules({ … })`. */
+    name: string;
+    cron: string;
+    timezone: string;
+    /** The tick this run is for (ISO). A run made up after the worker was down has the missed tick's time. */
+    scheduledAt: string;
+};
+export type ScheduleCtx<D extends PageTablesDesc | undefined = undefined> = FunctionCtx<{
+    schedule: ScheduleTick;
+}, D>;
+export type ScheduleDefinition<D extends PageTablesDesc | undefined = undefined> = {
+    /** Five fields: minute hour day-of-month month day-of-week (`'0 2 * * *'`: every day at 02:00). */
+    cron: string;
+    /** IANA name the cron is read in (`'UTC'`, `'America/Phoenix'`). */
+    timezone: string;
+    /** Throw to have the run recorded as failed; it is not retried, the next tick runs as usual. */
+    run: (ctx: ScheduleCtx<D>) => Promise<void>;
+};
+/** The `schedules` export: job name → definition. */
+export type Schedules<D extends PageTablesDesc | undefined = undefined> = Record<string, ScheduleDefinition<D>>;
+/**
+ * Author-side helper for `schedules.ts`:
+ *
+ * ```ts
+ * export const schedules = defineSchedules({
+ *   nightlySync: { cron: '0 2 * * *', timezone: 'UTC', run: async (ctx) => { … } },
+ * });
+ * ```
+ */
+export declare function defineSchedules<D extends PageTablesDesc | undefined = undefined>(schedules: Schedules<D>): Schedules<D>;
+/** The module a repository root or a sequence defines its jobs in. */
+export declare const SCHEDULES_MODULE = "schedules";
+/** A job's name in the build's function registry: `schedule.<name>` (a `noCase` function). */
+export declare const SCHEDULE_FUNCTION_PREFIX = "schedule.";
+export declare function scheduleFunctionName(name: string): string;
+/** When each job of a build runs, by job name; its code is `functions[scheduleFunctionName(name)]`. */
+export type ScheduleManifest = Record<string, {
+    cron: string;
+    timezone: string;
+}>;
+//# sourceMappingURL=schedules.d.ts.map

package/dist/core/functions/schedules.js

@@ -0,0 +1,20 @@
+/**
+ * Author-side helper for `schedules.ts`:
+ *
+ * ```ts
+ * export const schedules = defineSchedules({
+ *   nightlySync: { cron: '0 2 * * *', timezone: 'UTC', run: async (ctx) => { … } },
+ * });
+ * ```
+ */
+export function defineSchedules(schedules) {
+    return schedules;
+}
+/** The module a repository root or a sequence defines its jobs in. */
+export const SCHEDULES_MODULE = 'schedules';
+/** A job's name in the build's function registry: `schedule.<name>` (a `noCase` function). */
+export const SCHEDULE_FUNCTION_PREFIX = 'schedule.';
+export function scheduleFunctionName(name) {
+    return `${SCHEDULE_FUNCTION_PREFIX}${name}`;
+}
+//# sourceMappingURL=schedules.js.map

package/dist/core/functions/types.d.ts

@@ -1,48 +1,70 @@
-import type { FieldPath } from '../slot/path.js';
-import type { CaseContext, SystemContext, Writes } from '../context/types.js';
+import type { CaseOrchestrator } from '../case-orchestrator/types.js';
+import type { SystemContext } from '../context/types.js';
+import type { CaseInput } from '../case-orchestrator/types.js';
+import type { Db } from '../page/define.js';
+import type { PageTablesDesc, TypedDb } from '../page/typed.js';
 export type FuncOptions = {
     args?: Record<string, unknown>;
     description?: string;
 };
-/** First arg is CaseContext (or Slots when the sequence has no view). */
-export type ComputeFn<S = CaseContext, R = unknown> = (caseContext: S) => R | Promise<R>;
-export type FunctionCtx<Params extends object> = SystemContext & {
+/**
+ * Runtime function kinds. All of them take `ctx` and run on the Worker host; a host only needs to
+ * know whether a function takes `c` (the case).
+ *
+ * | kind               | signature                  | host    |
+ * | ------------------ | -------------------------- | ------- |
+ * | `case`             | `(c, ctx) => R`            | Worker  |
+ * | `noCase`           | `(ctx) => R`               | Worker  |
+ * | `orchestrator` | `(c, ctx) => R`            | Worker  |
+ *
+ * `define*` names map 1:1 onto kinds; tooling derives the kind from the define name.
+ * `orchestrator` has no define: the compiler stamps it on `orchestrator.ts`, and its `ctx`
+ * is a `CaseOrchestratorContext` instead of a `SystemContext`.
+ */
+export type FunctionKind = 'case' | 'noCase' | 'orchestrator';
+/** Kinds that take `ctx` and run on the Worker host. */
+export declare const WORKER_FUNCTION_KINDS: readonly ['case', 'noCase', 'orchestrator'];
+export type WorkerFunctionKind = (typeof WORKER_FUNCTION_KINDS)[number];
+export declare function isWorkerFunctionKind(kind: string): kind is WorkerFunctionKind;
+/**
+ * `ctx` of every function. `ctx.api.db` reads and writes records like a page script and its actions
+ * (15 §10.15 task 4): any row of the company and environment, each write its own transaction. `D` (the sequence's `PageTables`, bound by `__gen`) types them.
+ */
+export type FunctionCtx<Params extends object, D extends PageTablesDesc | undefined = undefined> = Omit<SystemContext, 'api'> & {
+    api: Omit<SystemContext['api'], 'db'> & {
+        db: D extends PageTablesDesc ? TypedDb<D> : Db;
+    };
     params: Params;
 };
-export type CustomFn<S = CaseContext, P extends object = object> = (caseContext: S, ctx: FunctionCtx<P>) => Promise<Writes | null>;
-/** Inbound webhook request payload. */
-export type WebHookFunctionParams = {
-    headers: Record<string, string | string[] | undefined>;
-    body: unknown;
-    rawBody?: string;
-};
-export type FunctionCall<Params extends object, Return> = (ctx: FunctionCtx<Params>) => Promise<Return>;
-export type WebHookFunction = FunctionCall<WebHookFunctionParams, void>;
-export type GetFirstMessageParams<S = CaseContext> = {
-    caseContext: S;
-};
-export type GetFirstMessageFunction<S = CaseContext> = FunctionCall<GetFirstMessageParams<S>, string>;
-/** Object-key → implementation type for platform-invoked entries. */
-export type SystemFuncMap = {
-    webhook: WebHookFunction;
-    getFirstMessage: GetFirstMessageFunction;
-};
+/**
+ * Bound to a case: `(c, ctx)`, `c` the case — the instance and its business root's id ({@link CaseInput}),
+ * not the page (the page is the conversation's). Return value is caller-defined (event handlers return nothing).
+ */
+export type CaseFn<S = CaseInput, P extends object = object, R = unknown, D extends PageTablesDesc | undefined = undefined> = (c: S, ctx: FunctionCtx<P, D>) => Promise<R>;
+/** Not bound to a case: `(ctx)` only. */
+export type NoCaseFn<P extends object = object, R = unknown, D extends PageTablesDesc | undefined = undefined> = (ctx: FunctionCtx<P, D>) => Promise<R>;
 type FuncMeta = {
     description?: string;
     args?: Record<string, unknown>;
 };
-/** One entry in a plain `functions` map (`{ name: define*Func(...) }`). */
-export type DefinedFunc = (FuncMeta & {
-    kind: 'compute' | 'boolCompute';
-    /** Implementation retained for compile → registry `code`; stripped from JSON via toFunctionRegistry. */
-    main: ComputeFn;
-}) | (FuncMeta & {
-    kind: 'custom';
-    main: CustomFn;
-}) | (FuncMeta & {
-    kind: 'system';
-    main: FunctionCall<object, unknown>;
-});
+export type DefinedCaseFunc<S = CaseInput, P extends object = object, R = unknown, D extends PageTablesDesc | undefined = undefined> = FuncMeta & {
+    kind: 'case';
+    main: CaseFn<S, P, R, D>;
+};
+export type DefinedNoCaseFunc<P extends object = object, R = unknown, D extends PageTablesDesc | undefined = undefined> = FuncMeta & {
+    kind: 'noCase';
+    main: NoCaseFn<P, R, D>;
+};
+/** The `orchestrator.ts` entry point, registered by the compiler (never authored in `functions`). */
+export type DefinedCaseOrchestratorFunc<S = CaseInput> = FuncMeta & {
+    kind: 'orchestrator';
+    main: CaseOrchestrator<S>;
+};
+/**
+ * One entry in a plain `functions` map (`{ name: define*Func(...) }`).
+ * Generics are kept (not erased) for the typed helpers that read a function's signature.
+ */
+export type DefinedFunc<S = any, P extends object = any, R = any> = DefinedCaseFunc<S, P, R> | DefinedNoCaseFunc<P, R> | DefinedCaseOrchestratorFunc<S>;
 /** Author map: key is the function name. */
 export type FuncMap = Record<string, DefinedFunc>;
 /** Map entry with name stamped from the key (for platform loaders). */
@@ -56,23 +78,12 @@ type RegistryCode = {
      */
     code?: string;
 };
-/** Compiled function registry entry shapes (JSON-safe). */
-export type FunctionRegistryEntry = (RegistryCode & {
-    kind: 'compute' | 'boolCompute';
-}) | (RegistryCode & {
-    kind: 'custom';
-    writes: FieldPath[];
-}) | (RegistryCode & {
-    kind: 'system';
-});
-export type FunctionRegistry = Record<string, FunctionRegistryEntry>;
-/** Compiled CaseContext projector (optional on SequenceBuild). */
-export type CaseContextViewRegistryEntry = {
-    kind: 'caseContextView';
-    /** Present on published builds; omitted on local serve overlay. */
-    code?: string;
+/** Compiled function registry entry (JSON-safe). Same shape for `functions` and `events`. */
+export type FunctionRegistryEntry = RegistryCode & {
+    kind: FunctionKind;
 };
-/** Stamp `name` from object keys when the platform loads a functions map. */
+export type FunctionRegistry = Record<string, FunctionRegistryEntry>;
+/** Plain-object FuncMap → array with `name` stamped (platform-side loaders). */
 export declare function toFuncRegistrations(functions: FuncMap): FuncRegistration[];
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/core/functions/types.js

@@ -1,4 +1,9 @@
-/** Stamp `name` from object keys when the platform loads a functions map. */
+/** Kinds that take `ctx` and run on the Worker host. */
+export const WORKER_FUNCTION_KINDS = ['case', 'noCase', 'orchestrator'];
+export function isWorkerFunctionKind(kind) {
+    return WORKER_FUNCTION_KINDS.includes(kind);
+}
+/** Plain-object FuncMap → array with `name` stamped (platform-side loaders). */
 export function toFuncRegistrations(functions) {
     return Object.entries(functions).map(([name, def]) => ({ ...def, name }));
 }

package/dist/core/office-hours/index.d.ts

@@ -0,0 +1,39 @@
+export type Window = {
+    start: string;
+    end: string;
+};
+export type Weekday = 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun';
+/** Company `office-hours.ts` config. */
+export type OfficeHours = {
+    /** IANA timezone name for the office (e.g. `'America/New_York'`). */
+    timezone: string;
+    /** Standard weekly open windows per weekday (`[]` means closed that weekday). */
+    week: Record<Weekday, Window[]>;
+    /** Recurring annual dates (`MM-DD`) whose `hours` replace `week` (`[]` means closed all day). */
+    holidays: {
+        date: string;
+        hours: Window[];
+    }[];
+    /** One-off calendar dates (`YYYY-MM-DD`) whose `hours` take precedence over both `holidays` and `week`. */
+    overrides: {
+        date: string;
+        hours: Window[];
+    }[];
+};
+/** The office hours now (`ctx.officeHours` of a page). `open` / `today` are filled by `resolveOfficeHours(now)`. */
+export type OfficeHoursSnapshot = OfficeHours & {
+    /** Whether the office is currently open at the resolved timestamp (`ctx.time.now`). */
+    open: boolean;
+    /** Effective open windows for today's date in `timezone` (after applying `overrides` / `holidays` / `week`). */
+    today: Window[];
+};
+export type ParseOfficeHoursResult = {
+    ok: true;
+    value: OfficeHours;
+} | {
+    ok: false;
+    issues: string[];
+};
+export declare function parseOfficeHours(value: unknown): ParseOfficeHoursResult;
+export declare function resolveOfficeHours(config: OfficeHours | null | undefined, now: number): OfficeHoursSnapshot | null;
+//# sourceMappingURL=index.d.ts.map