better-supabase 0.14.0 → 0.15.0

package/dist/blocks/compliance/index.d.ts

@@ -0,0 +1,325 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, t as AsyncResult } from "../../result-DZeA5KS6.js";
+import { t as StandardSchemaV1 } from "../../standard-DBV730sF.js";
+import { n as ExtraFields, r as FieldsOf } from "../../block-fields-BE7pInWZ.js";
+import { Ct as Events } from "../../events-vcqenSYU.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-CRpAHrp_.js";
+import { a as dbTransport, i as RpcClient, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DWZSJrwN.js";
+import { a as BlockTransportMiddleware, d as extendBlock, f as withBlockHooks, n as BlockHooks, p as wrapTransport } from "../../block-hooks-DZN2w69m.js";
+import { Sn as EntitySchema, c as BlockOf } from "../../define-block-BVcLQ3DF.js";
+//#region src/blocks/compliance/compliance.d.ts
+interface ComplianceOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  /**
+   * The module schema, or its API schema: `defineBlocks` passes it from
+   * `blocks.generated.ts`.
+   */
+  readonly schema?: string;
+  /**
+   * A Standard Schema for the control's extra columns
+   * (`blocks.compliance.options.extraColumns`), keyed by database name. It
+   * types and parses them on reads, and validates them on `saveControl`.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Compliance<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  readonly mappers?: readonly ErrorMapper[];
+}
+/** A compliance framework, such as SOC 2 or ISO 27001. */
+interface ControlFramework {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly key: string;
+  readonly name: string;
+  readonly version?: string;
+  readonly description?: string;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+interface ControlFrameworkInput {
+  /** Saving a key again updates that framework. */
+  readonly key: string;
+  readonly name: string;
+  readonly version?: string;
+  readonly description?: string;
+}
+/**
+ * `passing`: current evidence and no overdue task. `failing`: an overdue task,
+ * or only lapsed evidence. `not_started`: no evidence yet. `not_applicable`:
+ * out of scope.
+ */
+type ControlStatus = "passing" | "failing" | "not_started" | "not_applicable";
+/** A control. `F` types the extra columns the `fields` schema describes. */
+interface Control<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly frameworkId: string;
+  readonly code: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly ownerId?: string;
+  readonly applicable: boolean;
+  readonly status: ControlStatus;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
+}
+/** A control with its evidence (the newest 100) and evidence tasks. */
+interface ControlDetail<F extends object = Record<never, never>> extends Control<F> {
+  readonly evidence: readonly ControlEvidence[];
+  readonly tasks: readonly EvidenceTask[];
+}
+interface ControlInput<F extends object = Record<never, never>> {
+  readonly frameworkId: string;
+  /** Saving a code again in the framework updates that control. */
+  readonly code: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly ownerId?: string;
+  /** Default `true`. */
+  readonly applicable?: boolean;
+  /** Changes this control, code included. */
+  readonly controlId?: string;
+  /** The extra columns to set. */
+  readonly fields?: Partial<F>;
+}
+interface ControlListOptions {
+  readonly frameworkId?: string;
+  readonly status?: ControlStatus;
+  readonly ownerId?: string;
+  readonly pageSize?: number;
+}
+/** Evidence for a control: an attachment, a note, or both. */
+interface ControlEvidence {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly controlId: string;
+  readonly evidenceTaskId?: string;
+  readonly attachmentId?: string;
+  readonly note?: string;
+  readonly collectedBy?: string;
+  readonly collectedAt: Temporal.Instant;
+  /** The last day it counts; missing counts until it is removed. */
+  readonly validUntil?: Temporal.PlainDate;
+  readonly valid: boolean;
+}
+interface ControlEvidenceInput {
+  /** An attachment on the control (attachments block). */
+  readonly attachmentId?: string;
+  readonly note?: string;
+  /** Default: the task's interval past today, or no end without a task. */
+  readonly validUntil?: Temporal.PlainDate;
+  /** The recurring task this evidence answers. */
+  readonly evidenceTaskId?: string;
+}
+/** A recurring request for evidence, with an assignee and a due date. */
+interface EvidenceTask {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly controlId: string;
+  readonly title: string;
+  readonly assigneeId?: string;
+  readonly intervalDays: number;
+  readonly dueOn: Temporal.PlainDate;
+  readonly lastCollectedAt?: Temporal.Instant;
+  readonly active: boolean;
+  /** Active and past its due date. */
+  readonly overdue: boolean;
+  /** On `evidenceTasks` rows. */
+  readonly controlCode?: string;
+  readonly controlTitle?: string;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+interface EvidenceTaskInput {
+  readonly title: string;
+  /** Collecting evidence moves `dueOn` this many days past the collection. */
+  readonly intervalDays: number;
+  /** Default: today. */
+  readonly dueOn?: Temporal.PlainDate;
+  readonly assigneeId?: string;
+  /** Default `true`. */
+  readonly active?: boolean;
+  /** Changes this task instead of adding one. */
+  readonly evidenceTaskId?: string;
+}
+interface EvidenceTaskListOptions {
+  readonly controlId?: string;
+  readonly assigneeId?: string;
+  readonly overdueOnly?: boolean;
+}
+/** The status rollup of one framework. */
+interface ControlPosture {
+  readonly frameworkId: string;
+  readonly key: string;
+  readonly name: string;
+  readonly version?: string;
+  readonly total: number;
+  readonly passing: number;
+  readonly failing: number;
+  readonly notStarted: number;
+  readonly notApplicable: number;
+  readonly overdueTasks: number;
+}
+/** A policy members acknowledge, published as frozen versions. */
+interface Policy {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly key: string;
+  readonly title: string;
+  readonly ownerId?: string;
+  readonly requiresAcknowledgement: boolean;
+  /** The published version (versions block). */
+  readonly versionId?: string;
+  readonly versionNumber?: number;
+  readonly publishedAt?: Temporal.Instant;
+  readonly archivedAt?: Temporal.Instant;
+  /** When the caller acknowledged the published version. */
+  readonly acknowledgedAt?: Temporal.Instant;
+  /** Members who acknowledged the published version. */
+  readonly acknowledgedCount: number;
+  readonly memberCount: number;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+interface PolicyInput {
+  /** Saving a key again updates that policy. */
+  readonly key: string;
+  readonly title: string;
+  readonly ownerId?: string;
+  /** Default `true`. */
+  readonly requiresAcknowledgement?: boolean;
+  /** Changes this policy, key included. */
+  readonly policyId?: string;
+}
+interface PolicyListOptions {
+  readonly includeArchived?: boolean;
+  /** The published policies the caller still has to acknowledge. */
+  readonly pendingOnly?: boolean;
+}
+/** Who acknowledged a policy's published version. */
+interface PolicyAcknowledgements {
+  readonly policyId: string;
+  readonly versionId?: string;
+  readonly versionNumber?: number;
+  readonly members: readonly {
+    readonly userId: string;
+    /** Missing: not acknowledged yet. */
+    readonly acknowledgedAt?: Temporal.Instant;
+  }[];
+}
+interface Compliance<F extends object = Record<never, never>> {
+  /** Needs `controls.manage`. */
+  saveFramework(organizationId: string, input: ControlFrameworkInput): AsyncResult<ControlFramework>;
+  frameworks(organizationId: string): AsyncResult<readonly ControlFramework[]>;
+  /** Needs `controls.manage`. */
+  saveControl(input: ControlInput<F>): AsyncResult<Control<F>>;
+  getControl(controlId: string): AsyncResult<ControlDetail<F>>;
+  /** By framework and code. */
+  controls(organizationId: string, options?: ControlListOptions): AsyncResult<readonly Control<F>[]>;
+  /** Needs `controls.collect`, or being the evidence task's assignee. */
+  addEvidence(controlId: string, input: ControlEvidenceInput): AsyncResult<ControlEvidence>;
+  /** Needs `controls.manage`. */
+  removeEvidence(evidenceId: string): AsyncResult<ControlEvidence>;
+  /** Needs `controls.manage`. */
+  saveEvidenceTask(controlId: string, input: EvidenceTaskInput): AsyncResult<EvidenceTask>;
+  /** The earliest due first. */
+  evidenceTasks(organizationId: string, options?: EvidenceTaskListOptions): AsyncResult<readonly EvidenceTask[]>;
+  /** The status rollup per framework. */
+  posture(organizationId: string, frameworkId?: string): AsyncResult<readonly ControlPosture[]>;
+  /**
+   * Reports each overdue evidence task once per lapse; returns how many.
+   * Service role only; run it daily.
+   */
+  notifyOverdue(): AsyncResult<number>;
+  /** Needs `controls.manage`. */
+  savePolicy(organizationId: string, input: PolicyInput): AsyncResult<Policy>;
+  /**
+   * Publishes the policy's text as a new frozen version. Members acknowledge
+   * each published version again. Needs `controls.manage`.
+   */
+  publishPolicy(policyId: string, content: Readonly<Record<string, unknown>>, label?: string): AsyncResult<Policy>;
+  archivePolicy(policyId: string): AsyncResult<Policy>;
+  /**
+   * The caller acknowledges the published version. Needs
+   * `controls.acknowledge`.
+   */
+  acknowledgePolicy(policyId: string): AsyncResult<Policy>;
+  policies(organizationId: string, options?: PolicyListOptions): AsyncResult<readonly Policy[]>;
+  /** Every member and when they acknowledged. Needs `controls.read`. */
+  acknowledgements(policyId: string): AsyncResult<PolicyAcknowledgements>;
+}
+/** The `controls` SQL module as typed calls. */
+export declare function createCompliance<S extends StandardSchemaV1 | undefined = undefined>(options: ComplianceOptions<S>): Compliance<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/compliance/events.d.ts
+/** `control.saved`: a control was created or changed. */
+interface ControlSavedEventData {
+  readonly organizationId: string;
+  readonly controlId: string;
+  readonly frameworkId: string;
+  readonly code: string;
+}
+/** `control.evidence_added`: evidence was collected for a control. */
+interface ControlEvidenceAddedEventData {
+  readonly organizationId: string;
+  readonly controlId: string;
+  readonly evidenceId: string;
+  /** The recurring task the evidence answers, if any. */
+  readonly evidenceTaskId: string | null;
+}
+/** `evidence_task.missed`: a recurring evidence task passed its due date. */
+interface EvidenceTaskMissedEventData {
+  readonly organizationId: string;
+  readonly evidenceTaskId: string;
+  readonly controlId: string;
+  readonly assigneeId: string | null;
+  /** `YYYY-MM-DD`. */
+  readonly dueOn: string;
+}
+/** `policy.published`: a policy has a new current version. */
+interface PolicyPublishedEventData {
+  readonly organizationId: string;
+  readonly policyId: string;
+  readonly versionId: string;
+  readonly number: number;
+}
+/** `policy.acknowledged`: a member acknowledged a policy's current version. */
+interface PolicyAcknowledgedEventData {
+  readonly organizationId: string;
+  readonly policyId: string;
+  readonly versionId: string;
+  readonly userId: string;
+}
+/** The events of the `controls` block: type to data. */
+type ComplianceEvents = {
+  readonly "control.saved": ControlSavedEventData;
+  readonly "control.evidence_added": ControlEvidenceAddedEventData;
+  readonly "evidence_task.missed": EvidenceTaskMissedEventData;
+  readonly "policy.published": PolicyPublishedEventData;
+  readonly "policy.acknowledged": PolicyAcknowledgedEventData;
+};
+/** The `controls` block's event types, for its manifest and `onBlockEvent`. */
+export declare const complianceEvents: Events<ComplianceEvents>;
+//#endregion
+//#region src/blocks/compliance/manifest.d.ts
+/** The `controls` block's manifest (ADR 0029). */
+export declare const complianceBlock: BlockOf<"compliance", typeof createCompliance, ComplianceEvents>;
+//#endregion
+//#region src/blocks/compliance/schemas.d.ts
+/** What `saveFramework` takes. */
+export declare const controlFrameworkInputSchema: EntitySchema<ControlFrameworkInput>;
+/** What `saveControl` takes. */
+export declare const controlInputSchema: EntitySchema<ControlInput>;
+/** What `addEvidence` takes. */
+export declare const controlEvidenceInputSchema: EntitySchema<ControlEvidenceInput>;
+/** What `saveEvidenceTask` takes. */
+export declare const evidenceTaskInputSchema: EntitySchema<EvidenceTaskInput>;
+/** What `savePolicy` takes. */
+export declare const policyInputSchema: EntitySchema<PolicyInput>;
+//#endregion
+export { type BlockHooks, type BlockTransport, type BlockTransportMiddleware, type Compliance, type ComplianceEvents, type ComplianceOptions, type Control, type ControlDetail, type ControlEvidence, type ControlEvidenceAddedEventData, type ControlEvidenceInput, type ControlFramework, type ControlFrameworkInput, type ControlInput, type ControlListOptions, type ControlPosture, type ControlSavedEventData, type ControlStatus, type EvidenceTask, type EvidenceTaskInput, type EvidenceTaskListOptions, type EvidenceTaskMissedEventData, type Policy, type PolicyAcknowledgedEventData, type PolicyAcknowledgements, type PolicyInput, type PolicyListOptions, type PolicyPublishedEventData, type RpcClient, dbTransport, extendBlock, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };