@oxygen-agent/cli 1.717.11 → 1.739.0

package/node_modules/@oxygen/shared/dist/future-signup-lifecycle-projection.d.ts

@@ -0,0 +1,320 @@
+import { FUTURE_SIGNUP_LIFECYCLE_CONTRACT_VERSION, FUTURE_SIGNUP_LIFECYCLE_PROJECTION_CONTRACT_VERSION } from "./future-signup-events.js";
+/** Fixed destination-head authority. Contract upgrades cannot reset this stream. */
+export declare const FUTURE_SIGNUP_LIFECYCLE_PROJECTION_AUTHORITY: "oxygen_product_lifecycle";
+export declare const FUTURE_SIGNUP_LIFECYCLE_PROJECTION_FACT_TYPES: readonly ["trial_started", "paid", "lost", "subscription_ended", "workspace_deleted", "projection_refreshed"];
+export declare const FUTURE_SIGNUP_LIFECYCLE_PROJECTION_BILLING_STAGES: readonly ["free_trial", "paid", "lost"];
+export declare const FUTURE_SIGNUP_LIFECYCLE_PROJECTION_PREBILLING_STAGES: readonly ["lead", "interested", "demo_booked"];
+export declare const FUTURE_SIGNUP_LIFECYCLE_PROJECTION_SEMANTIC_STAGES: readonly ["lead", "interested", "demo_booked", "free_trial", "paid", "lost"];
+export declare const FUTURE_SIGNUP_LIFECYCLE_PROJECTION_ALIAS_TYPES: readonly ["clerk_organization", "clerk_user", "domain", "email", "stripe_customer"];
+export declare const FUTURE_SIGNUP_LIFECYCLE_PROJECTION_ACTIVITY_TYPES: readonly ["trial_started", "plan_paid", "customer_lost", "workspace_deleted"];
+export type FutureSignupLifecycleProjectionFactType = (typeof FUTURE_SIGNUP_LIFECYCLE_PROJECTION_FACT_TYPES)[number];
+export type FutureSignupLifecycleProjectionBillingStage = (typeof FUTURE_SIGNUP_LIFECYCLE_PROJECTION_BILLING_STAGES)[number];
+export type FutureSignupLifecycleProjectionPrebillingStage = (typeof FUTURE_SIGNUP_LIFECYCLE_PROJECTION_PREBILLING_STAGES)[number];
+export type FutureSignupLifecycleProjectionSemanticStage = (typeof FUTURE_SIGNUP_LIFECYCLE_PROJECTION_SEMANTIC_STAGES)[number];
+export type FutureSignupLifecycleProjectionAliasType = (typeof FUTURE_SIGNUP_LIFECYCLE_PROJECTION_ALIAS_TYPES)[number];
+export type FutureSignupLifecycleProjectionActivityType = (typeof FUTURE_SIGNUP_LIFECYCLE_PROJECTION_ACTIVITY_TYPES)[number];
+export type FutureSignupLifecycleProjectionSubjectKind = "company" | "person";
+export type FutureSignupLifecycleProjectionAction = "upsert" | "neutralize";
+export type FutureSignupLifecycleProjectionLossKind = "paid_churn" | "trial_non_conversion";
+export type FutureSignupLifecycleProjectionTerminationKind = "replaced" | "duplicate" | "unqualified";
+export type FutureSignupLifecycleProjectionMembershipRemovalReason = "member_removed" | "user_deleted" | "workspace_deleted";
+export type FutureSignupLifecycleProjectionMembershipContributor = {
+    clerk_membership_id: string;
+    clerk_org_id: string;
+    role: string;
+    is_creator: boolean;
+    active: boolean;
+    removed_reason: FutureSignupLifecycleProjectionMembershipRemovalReason | null;
+};
+/** Exact subject shape already emitted by the shipped v1 control builder. */
+export type FutureSignupLifecycleProjectionSubject = {
+    kind: FutureSignupLifecycleProjectionSubjectKind;
+    key: string;
+    billing_stage: FutureSignupLifecycleProjectionBillingStage | null;
+    stage_since: string | null;
+    aggregate_revision: number;
+    aggregate_fingerprint: string;
+    winning_clerk_org_id: string | null;
+    winning_fact_id: string | null;
+    winning_fact_revision: number | null;
+    source_state_revision: number;
+    membership_set_revision: number;
+    members_complete: true;
+    projection_action: FutureSignupLifecycleProjectionAction;
+    replacement_company_key: string | null;
+    departed_clerk_org_ids: string[];
+    oxygen_product_lifecycle: {
+        revision: number;
+        fingerprint: string;
+    };
+    external_identities: Array<{
+        provider: "clerk";
+        object: "user" | "organization";
+        id: string;
+    }>;
+    natural_identity: {
+        email: string | null;
+        domain: string | null;
+    };
+    display: {
+        first_name: string | null;
+        last_name: string | null;
+        company_name: string | null;
+    };
+    represented_clerk_org_ids: string[];
+    represented_company_keys: string[];
+    membership_ids: string[];
+    membership_contributors: FutureSignupLifecycleProjectionMembershipContributor[];
+};
+export type FutureSignupLifecycleProjectionOrganizationState = {
+    clerk_org_id: string;
+    company_key: string;
+    company_key_history: string[];
+    normalized_domain: string | null;
+    billing_stage: FutureSignupLifecycleProjectionBillingStage | null;
+    stage_since: string | null;
+    loss_kind: FutureSignupLifecycleProjectionLossKind | null;
+    winning_fact_id: string | null;
+    winning_fact_revision: number | null;
+    organization_revision: number;
+    billing_revision: number;
+    state_revision: number;
+    membership_set_revision: number;
+    members_complete: boolean;
+    state_fingerprint: string;
+    membership_set_fingerprint: string;
+    workspace_deleted_at: string | null;
+    workspace_deleted_fact_id: string | null;
+    workspace_deleted_fact_revision: number | null;
+};
+export type FutureSignupLifecycleProjectionMembershipState = {
+    clerk_membership_id: string;
+    journey_id: string | null;
+    clerk_user_id: string;
+    clerk_org_id: string;
+    role: string;
+    is_creator: boolean;
+    contributes_to_lifecycle: boolean;
+    membership_created_at: string;
+    membership_revision: number;
+    state_fingerprint: string;
+    removed_at: string | null;
+    removed_reason: FutureSignupLifecycleProjectionMembershipRemovalReason | null;
+};
+export type FutureSignupLifecycleProjectionSourceFact = {
+    fact_id: string;
+    fact_revision: number;
+    contract_version: typeof FUTURE_SIGNUP_LIFECYCLE_CONTRACT_VERSION;
+    fact_type: FutureSignupLifecycleProjectionFactType;
+    clerk_org_id: string;
+    occurred_at: string;
+    source: "clerk" | "clerk_org_deletion" | "stripe";
+    source_event_id: string;
+    source_revision: number;
+    stripe_customer_id: string | null;
+    stripe_subscription_id: string | null;
+    stripe_invoice_id: string | null;
+    stripe_period_start: string | null;
+    stripe_period_end: string | null;
+    amount_paid_cents: number | null;
+    currency: string | null;
+    loss_kind: FutureSignupLifecycleProjectionLossKind | null;
+    termination_kind: FutureSignupLifecycleProjectionTerminationKind | null;
+};
+export type FutureSignupLifecycleProjectionSnapshot = {
+    complete: true;
+    causal_clerk_org_id: string;
+    organization_states: FutureSignupLifecycleProjectionOrganizationState[];
+    membership_states: FutureSignupLifecycleProjectionMembershipState[];
+    subjects: FutureSignupLifecycleProjectionSubject[];
+    subject_set_fingerprint: string;
+    snapshot_fingerprint: string;
+};
+export type FutureSignupLifecycleProjectionActivity = {
+    type: FutureSignupLifecycleProjectionActivityType | "note";
+    source_provider: typeof FUTURE_SIGNUP_LIFECYCLE_PROJECTION_AUTHORITY;
+    provider_event_id: string;
+    occurred_at: string;
+    summary: string;
+    subject_keys: string[];
+    metadata: {
+        source_fact_id: string;
+        source_fact_revision: number;
+        causal_clerk_org_id: string;
+        loss_kind: FutureSignupLifecycleProjectionLossKind | null;
+        termination_kind: FutureSignupLifecycleProjectionTerminationKind | null;
+    };
+};
+/** Exact plaintext envelope already emitted by the shipped v1 control builder. */
+export type FutureSignupLifecycleProjectionEnvelope = {
+    contract_version: typeof FUTURE_SIGNUP_LIFECYCLE_PROJECTION_CONTRACT_VERSION;
+    event_id: string;
+    event_type: "lifecycle_projection";
+    fact_id: string;
+    fact_revision: number;
+    occurred_at: string;
+    provider: "oxygen";
+    provider_event_id: string;
+    upstream: {
+        provider: FutureSignupLifecycleProjectionSourceFact["source"];
+        provider_event_id: string;
+        source_revision: number;
+    };
+    source_fact: FutureSignupLifecycleProjectionSourceFact;
+    snapshot: FutureSignupLifecycleProjectionSnapshot;
+    activity: FutureSignupLifecycleProjectionActivity;
+    producer: {
+        environment: "dev" | "production";
+        version: string;
+        commitSha: string;
+    };
+    validation: {
+        synthetic: false;
+        no_send: true;
+    };
+};
+export type FutureSignupLifecycleProjectionAlias = {
+    type: FutureSignupLifecycleProjectionAliasType;
+    value: string;
+};
+export type FutureSignupLifecycleProjectionLookupIdentity = {
+    type: "domain";
+    value: string;
+};
+export type FutureSignupLifecycleProjectionPrebillingCandidate = {
+    stage: FutureSignupLifecycleProjectionPrebillingStage;
+    occurred_at: string;
+    source_event_id: string;
+};
+/** Closed destination view derived from, but not confused with, the shipped v1. */
+export type FutureSignupLifecycleProjectionNormalizedSubject = {
+    kind: FutureSignupLifecycleProjectionSubjectKind;
+    key: string;
+    /** Identities the apply layer may assert or attach to the destination record. */
+    aliases: FutureSignupLifecycleProjectionAlias[];
+    /** Lookup-only identity for a historical tombstone; never asserted or moved. */
+    lookup_identities: FutureSignupLifecycleProjectionLookupIdentity[];
+    display: FutureSignupLifecycleProjectionSubject["display"];
+    aggregate_revision: number;
+    aggregate_fingerprint: string;
+    source_state_revision: number;
+    membership_set_revision: number;
+    members_complete: true;
+    projection_action: FutureSignupLifecycleProjectionAction;
+    replacement_company_key: string | null;
+    departed_clerk_org_ids: string[];
+    billing_stage: FutureSignupLifecycleProjectionBillingStage | null;
+    stage_since: string | null;
+    loss_kind: FutureSignupLifecycleProjectionLossKind | null;
+    winning_clerk_org_id: string | null;
+    winning_fact_id: string | null;
+    winning_fact_revision: number | null;
+    /** v1 carries no prebilling evidence, so normalization never invents one. */
+    prebilling_candidate: FutureSignupLifecycleProjectionPrebillingCandidate | null;
+    membership_contributors: FutureSignupLifecycleProjectionMembershipContributor[];
+};
+export type FutureSignupLifecycleProjectionParticipant = {
+    kind: FutureSignupLifecycleProjectionSubjectKind;
+    key: string;
+    role: "primary" | "related";
+};
+export type FutureSignupLifecycleProjectionNormalizedActivity = {
+    emit: true;
+    type: FutureSignupLifecycleProjectionActivityType;
+    source_provider: typeof FUTURE_SIGNUP_LIFECYCLE_PROJECTION_AUTHORITY;
+    provider_event_id: string;
+    occurred_at: string;
+    summary: string;
+    participants: FutureSignupLifecycleProjectionParticipant[];
+} | {
+    emit: false;
+    type: null;
+    source_provider: null;
+    provider_event_id: null;
+    occurred_at: null;
+    summary: null;
+    participants: [];
+};
+export type FutureSignupLifecycleProjectionFingerprintSet = {
+    source_fact_fingerprint: string;
+    subject_set_fingerprint: string;
+    snapshot_fingerprint: string;
+    projection_fingerprint: string;
+};
+export type FutureSignupLifecycleProjectionIdempotencyKeys = {
+    delivery_receipt: string;
+    activity: string | null;
+    subjects: Array<{
+        kind: FutureSignupLifecycleProjectionSubjectKind;
+        key: string;
+        idempotency_key: string;
+    }>;
+};
+export type FutureSignupLifecycleProjectionNormalizedProjection = {
+    contract_version: typeof FUTURE_SIGNUP_LIFECYCLE_PROJECTION_CONTRACT_VERSION;
+    authority: typeof FUTURE_SIGNUP_LIFECYCLE_PROJECTION_AUTHORITY;
+    event_id: string;
+    occurred_at: string;
+    source_fact: FutureSignupLifecycleProjectionSourceFact;
+    snapshot: {
+        complete: true;
+        causal_clerk_org_id: string;
+        subjects: FutureSignupLifecycleProjectionNormalizedSubject[];
+    };
+    activity: FutureSignupLifecycleProjectionNormalizedActivity;
+    validation: {
+        synthetic: false;
+        no_send: true;
+    };
+};
+export type NormalizedFutureSignupLifecycleProjectionEnvelope = {
+    /** Canonical clone of the exact shipped v1 plaintext. */
+    envelope: FutureSignupLifecycleProjectionEnvelope;
+    /** Closed destination-facing projection derived from that plaintext. */
+    projection: FutureSignupLifecycleProjectionNormalizedProjection;
+    fingerprints: FutureSignupLifecycleProjectionFingerprintSet;
+    idempotency_keys: FutureSignupLifecycleProjectionIdempotencyKeys;
+};
+export type FutureSignupLifecycleProjectionStageMapping = Record<FutureSignupLifecycleProjectionSemanticStage, string>;
+export type FutureSignupLifecycleProjectionDestinationApplyOptions = {
+    objects: {
+        people: "people";
+        companies: "companies";
+    };
+    stage_tokens: {
+        people: FutureSignupLifecycleProjectionStageMapping;
+        companies: FutureSignupLifecycleProjectionStageMapping;
+    };
+    /** Destination-only exact member identity. Never appears in the control envelope. */
+    owner_if_blank: {
+        workspace_user_id: string;
+    } | null;
+    activity_policy: {
+        customer_lifecycle_facts: "emit_envelope_activity";
+        projection_refreshed: "suppress";
+        subscription_ended: "suppress";
+        participants: "envelope_subjects_only";
+        idempotency: "event_id";
+    };
+};
+export type NormalizedFutureSignupLifecycleProjectionDestinationApplyOptions = {
+    apply_options: FutureSignupLifecycleProjectionDestinationApplyOptions;
+    apply_options_fingerprint: string;
+};
+/** Typed, PII-free parse failure. Raw values are intentionally never reflected. */
+export declare class FutureSignupLifecycleProjectionContractError extends TypeError {
+    readonly path: string;
+    readonly rule: string;
+    readonly code = "future_signup_lifecycle_projection_invalid";
+    constructor(path: string, rule: string);
+}
+/** Exact fingerprint algorithm used by the shipped v1 control builder. */
+export declare function futureSignupLifecycleProjectionFingerprints(input: {
+    eventId: string;
+    sourceFact: FutureSignupLifecycleProjectionSourceFact;
+    snapshot: Omit<FutureSignupLifecycleProjectionSnapshot, "subject_set_fingerprint" | "snapshot_fingerprint">;
+}): FutureSignupLifecycleProjectionFingerprintSet;
+export declare function parseFutureSignupLifecycleProjectionJson(body: string): NormalizedFutureSignupLifecycleProjectionEnvelope;
+/** Validate shipped v1 and derive the closed destination view. No writes or sends. */
+export declare function normalizeFutureSignupLifecycleProjectionEnvelope(value: unknown): NormalizedFutureSignupLifecycleProjectionEnvelope;
+export declare function normalizeFutureSignupLifecycleProjectionDestinationApplyOptions(value: unknown): NormalizedFutureSignupLifecycleProjectionDestinationApplyOptions;