@pome-sh/checks 0.1.0

package/dist/_types/twin-slack/src/types.d.ts

@@ -0,0 +1,182 @@
+import type { TwinDatabase } from "../../sdk/db.js";
+export type { RecorderEvent } from "../../wire/index.js";
+export type SlackTwinDatabase = TwinDatabase;
+export type SeedTeam = {
+    id?: string;
+    name?: string;
+    domain?: string;
+};
+export type SeedUser = {
+    id?: string;
+    name: string;
+    real_name?: string;
+    email?: string;
+    is_bot?: boolean;
+    is_admin?: boolean;
+    tz?: string;
+    profile?: Record<string, unknown>;
+};
+export type SeedReaction = {
+    name: string;
+    user: string;
+};
+export type SeedMessage = {
+    ts?: string;
+    user: string;
+    text: string;
+    thread_ts?: string;
+    reactions?: SeedReaction[];
+};
+export type SeedChannel = {
+    id?: string;
+    name: string;
+    is_private?: boolean;
+    topic?: string;
+    purpose?: string;
+    creator?: string;
+    members?: string[];
+    messages?: SeedMessage[];
+};
+export type SeedEmoji = {
+    name: string;
+    /** Absolute image URL. Ignored when `alias` is set. */
+    url?: string;
+    /** Alias target name → stored as `alias:<name>`. */
+    alias?: string;
+};
+export type SlackStateSeed = {
+    team?: SeedTeam;
+    users?: SeedUser[];
+    channels?: SeedChannel[];
+    emoji?: SeedEmoji[];
+};
+export type WorkspaceRow = {
+    id: string;
+    name: string;
+    domain: string;
+    url: string;
+    enterprise_id: string | null;
+    created_at: string;
+    entity_counter: number;
+};
+export type UserRow = {
+    id: string;
+    team_id: string;
+    name: string;
+    real_name: string;
+    display_name: string;
+    email: string | null;
+    is_bot: 0 | 1;
+    is_admin: 0 | 1;
+    deleted: 0 | 1;
+    tz: string;
+    profile_json: string;
+    created_at: string;
+    updated_at: string;
+};
+export type ChannelRow = {
+    id: string;
+    team_id: string;
+    name: string;
+    is_channel: 0 | 1;
+    is_group: 0 | 1;
+    is_im: 0 | 1;
+    is_mpim: 0 | 1;
+    is_private: 0 | 1;
+    is_archived: 0 | 1;
+    topic: string;
+    purpose: string;
+    creator: string;
+    created_at: string;
+    ts_counter: number;
+    dm_signature: string | null;
+};
+export type ChannelMemberRow = {
+    channel_id: string;
+    user_id: string;
+    joined_at: string;
+    last_read: string;
+};
+export type MessageRow = {
+    channel_id: string;
+    ts: string;
+    user_id: string;
+    text: string;
+    subtype: string | null;
+    thread_ts: string | null;
+    reply_count: number;
+    reply_users_count: number;
+    latest_reply: string | null;
+    edited_user_id: string | null;
+    edited_ts: string | null;
+    blocks_json: string;
+    attachments_json: string;
+    bot_id: string | null;
+    app_id: string | null;
+    username: string | null;
+    icon_url: string | null;
+    icon_emoji: string | null;
+};
+export type ReactionRow = {
+    channel_id: string;
+    message_ts: string;
+    name: string;
+    user_id: string;
+    added_at: string;
+};
+export type PinRow = {
+    channel_id: string;
+    message_ts: string;
+    pinned_by: string;
+    pinned_at: string;
+};
+export type FileRow = {
+    id: string;
+    team_id: string;
+    user_id: string;
+    name: string;
+    title: string;
+    mimetype: string;
+    filetype: string;
+    size: number;
+    url_private: string;
+    channels_json: string;
+    deleted: 0 | 1;
+    content: string | null;
+    created_at: string;
+};
+export type BookmarkRow = {
+    id: string;
+    channel_id: string;
+    title: string;
+    link: string;
+    emoji: string | null;
+    type: string;
+    created_by: string;
+    created_at: string;
+};
+export type ScheduledMessageRow = {
+    id: string;
+    channel_id: string;
+    user_id: string;
+    text: string;
+    thread_ts: string | null;
+    post_at: number;
+    date_created: number;
+    blocks_json: string;
+};
+export type CanvasRow = {
+    id: string;
+    team_id: string;
+    title: string;
+    markdown: string;
+    channel_id: string | null;
+    created_by: string;
+    created_at: string;
+    updated_at: string;
+};
+export type EmojiRow = {
+    team_id: string;
+    name: string;
+    value: string;
+};

package/dist/_types/twin-stripe/src/check-kind.d.ts

@@ -0,0 +1,3 @@
+import type { CheckDefinition } from "../../sdk/checks.js";
+import type { StripeCheckState } from "./check-state.js";
+export type Check<TArgs extends Record<string, string>> = CheckDefinition<StripeCheckState, TArgs>;

package/dist/_types/twin-stripe/src/check-state.d.ts

@@ -0,0 +1,107 @@
+import { type CheckOutcome } from "../../sdk/checks.js";
+export interface StripeCheckStatePaymentIntent {
+    id?: string;
+    amount?: number;
+    currency?: string;
+    status?: string;
+    latest_charge?: string | null;
+}
+export interface StripeCheckStateCharge {
+    id?: string;
+    amount?: number;
+    amount_refunded?: number;
+    currency?: string;
+    status?: string;
+    refunded?: boolean;
+    paid?: boolean;
+    payment_intent?: string | null;
+    balance_transaction?: string | null;
+}
+export interface StripeCheckStateBalanceTransaction {
+    id?: string;
+    amount?: number;
+    source?: string | null;
+    status?: string;
+    type?: string;
+}
+export interface StripeCheckStateEvent {
+    id?: string;
+    type?: string;
+    data?: {
+        object?: unknown;
+    } | null;
+    created?: number;
+}
+export interface StripeCheckStateRefund {
+    id?: string;
+    amount?: number;
+    currency?: string;
+    status?: string;
+    charge?: string | null;
+    payment_intent?: string | null;
+}
+export interface StripeCheckState {
+    payment_intents?: StripeCheckStatePaymentIntent[] | null;
+    charges?: StripeCheckStateCharge[] | null;
+    balance_transactions?: StripeCheckStateBalanceTransaction[] | null;
+    events?: StripeCheckStateEvent[] | null;
+    refunds?: StripeCheckStateRefund[] | null;
+}
+/** twin-github's and twin-slack's verdict type, same shape and same reason: a
+ *  resolver must be able to say WHY it found nothing, because the ways of
+ *  finding nothing get different verdicts.
+ *
+ *  F-1197 added the pointers, also twin-github's: `path` is where the resolution
+ *  landed, `searched` is the collection a failed lookup scanned — absent when the
+ *  export carried no such collection, because a citation that resolves to
+ *  nothing is the affordance-to-nowhere that ticket removes. */
+export type Resolved<T> = {
+    found: T;
+    path: string;
+} | {
+    missing: string;
+    searched?: string;
+};
+/** The exported collections a pointer can address (F-1197). Named because seven
+ *  declarations reach for them, and because these are WIRE names — `refunds`,
+ *  not `refund_rows` — which is exactly the distinction this file's header
+ *  spends thirty lines on. A literal typed out at each call site is a chance to
+ *  reintroduce a row-column name that resolves to nothing. */
+export declare const PAYMENT_INTENTS_PATH: string;
+export declare const CHARGES_PATH: string;
+export declare const EVENTS_PATH: string;
+export declare const REFUNDS_PATH: string;
+/** The `skipped` outcome an unresolvable lookup produces, citing where it
+ *  looked. Stripe abstains where twin-github fails, on twin-slack's precedent
+ *  (see `resolveCharge`), so this is `missOutcome` with `skipped`. */
+export declare function missSkip(miss: {
+    missing: string;
+    searched?: string;
+}): CheckOutcome;
+/**
+ * The charge a criterion names, with the three outcomes a refund assertion has
+ * to tell apart:
+ *   - no `charges` key at all → `state_incomplete`; nothing can be attested
+ *   - present but this charge absent → `charge_not_found`. A SKIP rather than a
+ *     verdict, on twin-slack's `resolveChannel` precedent: we cannot attest a
+ *     positive over state we do not have, and for a negative a missing selector
+ *     would hand a wrong agent a free pass.
+ *   - found → the predicate evaluates. A present charge with zero refunds is a
+ *     TRUE vacuous pass for a negative and a TRUE fail for a positive.
+ *
+ * Comparison is EXACT. A Stripe charge id is an opaque identifier the twin
+ * minted, not a human-typed name, so the case-insensitive `#`-tolerant matching
+ * twin-slack does for channel names would only widen what a typo can hit.
+ */
+export declare function resolveCharge(state: StripeCheckState, chargeId: string): Resolved<StripeCheckStateCharge>;
+/**
+ * Every refund row against a charge, or the reason we cannot say.
+ *
+ * Resolves the CHARGE first and skips when it is missing, so "this charge has
+ * no refunds" and "there is no such charge" never reach the same verdict —
+ * they are the two answers a count assertion must not conflate.
+ *
+ * An EMPTY list is a real answer, deliberately distinct from either skip: a
+ * seeded charge nobody refunded really does have zero refunds.
+ */
+export declare function refundsOnCharge(state: StripeCheckState, chargeId: string): Resolved<StripeCheckStateRefund[]>;

package/dist/_types/twin-stripe/src/checks.d.ts

@@ -0,0 +1,22 @@
+export type { Check } from "./check-kind.js";
+export type { StripeCheckState, StripeCheckStateBalanceTransaction, StripeCheckStateCharge, StripeCheckStateEvent, StripeCheckStatePaymentIntent, StripeCheckStateRefund, } from "./check-state.js";
+export declare const STRIPE_CHECKS: readonly [import("./check-kind.js").Check<{
+    amount: string;
+}>, import("./check-kind.js").Check<{
+    status: string;
+}>, import("./check-kind.js").Check<{
+    status: string;
+}>, import("./check-kind.js").Check<{
+    status: string;
+}>, import("./check-kind.js").Check<{
+    event_type: string;
+}>, import("./check-kind.js").Check<{
+    charge: string;
+}>, import("./check-kind.js").Check<{
+    charge: string;
+    count: string;
+}>, import("./check-kind.js").Check<{
+    charge: string;
+}>, import("./check-kind.js").Check<{
+    error_type: string;
+}>, import("./check-kind.js").Check<Record<string, never>>, import("./check-kind.js").Check<Record<string, never>>];

package/dist/_types/twin-stripe/src/seed.d.ts

@@ -0,0 +1,213 @@
+import { z } from "zod";
+import { type FailureInjectionStore } from "../../sdk/failure-injection-rules.js";
+import type { SeedState, TwinStripeDatabase } from "./types.js";
+export type { SeedState } from "./types.js";
+export declare const DEFAULT_SID = "default";
+export declare const DEFAULT_API_KEY = "sk_test_pome_default";
+declare const paymentIntentSeedSchema: z.ZodObject<{
+    id: z.ZodString;
+    account_id: z.ZodString;
+    amount: z.ZodNumber;
+    currency: z.ZodString;
+    status: z.ZodEnum<{
+        requires_payment_method: "requires_payment_method";
+        requires_confirmation: "requires_confirmation";
+        requires_action: "requires_action";
+        processing: "processing";
+        requires_capture: "requires_capture";
+        canceled: "canceled";
+        succeeded: "succeeded";
+    }>;
+    payment_method_types: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    next_action: z.ZodOptional<z.ZodNullable<z.ZodUnknown>>;
+    latest_charge_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    capture_method: z.ZodDefault<z.ZodString>;
+    confirmation_method: z.ZodDefault<z.ZodString>;
+    idempotency_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    crypto_deposit: z.ZodOptional<z.ZodNullable<z.ZodUnknown>>;
+    client_secret: z.ZodString;
+    created: z.ZodNumber;
+    updated: z.ZodNumber;
+    canceled_at: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    captured_at: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+declare const chargeSeedSchema: z.ZodObject<{
+    id: z.ZodString;
+    account_id: z.ZodString;
+    payment_intent_id: z.ZodString;
+    amount: z.ZodNumber;
+    amount_captured: z.ZodDefault<z.ZodNumber>;
+    amount_refunded: z.ZodDefault<z.ZodNumber>;
+    status: z.ZodEnum<{
+        succeeded: "succeeded";
+        pending: "pending";
+        failed: "failed";
+    }>;
+    balance_transaction_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    captured: z.ZodDefault<z.ZodBoolean>;
+    currency: z.ZodString;
+    created: z.ZodNumber;
+}, z.core.$strip>;
+declare const refundSeedSchema: z.ZodObject<{
+    id: z.ZodString;
+    account_id: z.ZodString;
+    charge_id: z.ZodString;
+    payment_intent_id: z.ZodString;
+    amount: z.ZodNumber;
+    currency: z.ZodString;
+    status: z.ZodEnum<{
+        canceled: "canceled";
+        succeeded: "succeeded";
+        pending: "pending";
+        failed: "failed";
+    }>;
+    reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    balance_transaction_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    idempotency_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created: z.ZodNumber;
+}, z.core.$strip>;
+declare const balanceTransactionSeedSchema: z.ZodObject<{
+    id: z.ZodString;
+    account_id: z.ZodString;
+    type: z.ZodString;
+    amount: z.ZodNumber;
+    fee: z.ZodDefault<z.ZodNumber>;
+    net: z.ZodNumber;
+    currency: z.ZodString;
+    source_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    source_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    available_on: z.ZodNumber;
+    status: z.ZodDefault<z.ZodEnum<{
+        pending: "pending";
+        available: "available";
+    }>>;
+    created: z.ZodNumber;
+}, z.core.$strip>;
+export type PaymentIntentSeed = z.infer<typeof paymentIntentSeedSchema>;
+export type ChargeSeed = z.infer<typeof chargeSeedSchema>;
+export type RefundSeed = z.infer<typeof refundSeedSchema>;
+export type BalanceTransactionSeed = z.infer<typeof balanceTransactionSeedSchema>;
+export declare const seedSchema: z.ZodObject<{
+    api_keys: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        sid: z.ZodString;
+        account_id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    failure_injection: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        method: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        path: z.ZodString;
+        attempt: z.ZodNumber;
+        mode: z.ZodDefault<z.ZodEnum<{
+            before_handler: "before_handler";
+            after_handler: "after_handler";
+        }>>;
+        status: z.ZodNumber;
+        body: z.ZodUnknown;
+    }, z.core.$strip>>>;
+    payment_intents: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        account_id: z.ZodString;
+        amount: z.ZodNumber;
+        currency: z.ZodString;
+        status: z.ZodEnum<{
+            requires_payment_method: "requires_payment_method";
+            requires_confirmation: "requires_confirmation";
+            requires_action: "requires_action";
+            processing: "processing";
+            requires_capture: "requires_capture";
+            canceled: "canceled";
+            succeeded: "succeeded";
+        }>;
+        payment_method_types: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        next_action: z.ZodOptional<z.ZodNullable<z.ZodUnknown>>;
+        latest_charge_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        capture_method: z.ZodDefault<z.ZodString>;
+        confirmation_method: z.ZodDefault<z.ZodString>;
+        idempotency_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        crypto_deposit: z.ZodOptional<z.ZodNullable<z.ZodUnknown>>;
+        client_secret: z.ZodString;
+        created: z.ZodNumber;
+        updated: z.ZodNumber;
+        canceled_at: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        captured_at: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>>>;
+    charges: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        account_id: z.ZodString;
+        payment_intent_id: z.ZodString;
+        amount: z.ZodNumber;
+        amount_captured: z.ZodDefault<z.ZodNumber>;
+        amount_refunded: z.ZodDefault<z.ZodNumber>;
+        status: z.ZodEnum<{
+            succeeded: "succeeded";
+            pending: "pending";
+            failed: "failed";
+        }>;
+        balance_transaction_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        captured: z.ZodDefault<z.ZodBoolean>;
+        currency: z.ZodString;
+        created: z.ZodNumber;
+    }, z.core.$strip>>>;
+    refunds: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        account_id: z.ZodString;
+        charge_id: z.ZodString;
+        payment_intent_id: z.ZodString;
+        amount: z.ZodNumber;
+        currency: z.ZodString;
+        status: z.ZodEnum<{
+            canceled: "canceled";
+            succeeded: "succeeded";
+            pending: "pending";
+            failed: "failed";
+        }>;
+        reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        balance_transaction_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        idempotency_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        created: z.ZodNumber;
+    }, z.core.$strip>>>;
+    balance_transactions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        account_id: z.ZodString;
+        type: z.ZodString;
+        amount: z.ZodNumber;
+        fee: z.ZodDefault<z.ZodNumber>;
+        net: z.ZodNumber;
+        currency: z.ZodString;
+        source_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        source_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        available_on: z.ZodNumber;
+        status: z.ZodDefault<z.ZodEnum<{
+            pending: "pending";
+            available: "available";
+        }>>;
+        created: z.ZodNumber;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare function parseSeed(input: unknown): SeedState;
+/**
+ * Boot-time seed loader: prefer `POME_SEED_JSON` env (set by the cloud
+ * control-plane from the CLI-supplied scenario seed; see FDRS-353 +
+ * FDRS-361) and fall back to `defaultSeed()` when the env is absent.
+ *
+ * Unwrap contract (FDRS-365 + FDRS-369): scenarios may send the
+ * canonical wrapped shape `{ stripe: { seed: {...} } }` (what scenario
+ * 14 uses) or the flat shape `{ payment_intents: [...], ... }`. We peel
+ * `body.stripe?.seed ?? body` so both shapes work end-to-end without
+ * a cloud-side rewrite. Throws on malformed JSON or schema-invalid
+ * seed, so a misconfigured cloud deploy fails the twin server's
+ * healthz instead of silently booting with an empty Stripe world.
+ */
+/**
+ * `Record<string, string | undefined>` rather than `NodeJS.ProcessEnv`, which is
+ * structurally the same thing but an AMBIENT global. This signature is vendored
+ * into `@pome-sh/checks`'s published declarations, and an ambient reference there
+ * makes a consumer's `tsc` fail with TS2503 unless they happen to have
+ * `@types/node` installed — a dependency this package should not impose to
+ * describe a plain string map.
+ */
+export declare function loadSeedFromEnv(env?: Record<string, string | undefined>): SeedState;
+export declare function defaultSeed(): SeedState;
+export declare function applySeed(db: TwinStripeDatabase, seed: SeedState, failureInjection?: FailureInjectionStore): void;