@sylphx/contract 0.2.0

package/dist/schemas/billing.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Billing — BaaS plane schemas for the deployed-app SDK (`@sylphx/sdk`).
+ * Mirrors the runtime API at `GET /billing/plans`, `/billing/subscription`,
+ * `POST /billing/checkout`, `/billing/portal`, `GET /billing/balance`,
+ * `/billing/usage` (see `apps/runtime/src/server/runtime/schemas/billing.ts`).
+ *
+ * Distinct from `billing-console.ts` (Management plane; Console UI / dev
+ * subscription management), `billing-settings.ts` (org billing configuration),
+ * and `admin-billing.ts` (super-admin cross-org ops). The BaaS surface is the
+ * end-user subscription flow a deployed application exposes to *its* users —
+ * the plan catalog shape, checkout/portal envelope, and balance/usage metrics
+ * all evolve independently of the Console counterparts (different enum
+ * values, different field names, different envelope keys).
+ *
+ * Names are prefixed `SdkBilling*` to disambiguate from the Management-plane
+ * `BillingPlan` / `Subscription` symbols that share the contract barrel.
+ */
+import { Schema } from 'effect';
+/** Billing interval for the end-user subscription. */
+export declare const SdkBillingInterval: Schema.Literal<["monthly", "annual", "lifetime"]>;
+export type SdkBillingInterval = typeof SdkBillingInterval.Type;
+/** Lifecycle status for a BaaS-plane subscription (note: spells `canceled`,
+ * whereas the Console plane uses `cancelled` — reflects the underlying REST
+ * contract). */
+export declare const SdkBillingSubscriptionStatus: Schema.Literal<["active", "canceled", "past_due", "incomplete", "trialing", "paused"]>;
+export type SdkBillingSubscriptionStatus = typeof SdkBillingSubscriptionStatus.Type;
+/** Health status bucket for the end-user balance response. */
+export declare const SdkBillingStatusLevel: Schema.Literal<["healthy", "low", "critical", "exhausted"]>;
+export type SdkBillingStatusLevel = typeof SdkBillingStatusLevel.Type;
+/** Billing type surfaced to the deployed app. */
+export declare const SdkBillingType: Schema.Literal<["prepaid", "postpaid", "enterprise"]>;
+export type SdkBillingType = typeof SdkBillingType.Type;
+/** Trust level surfaced to the deployed app (note literal values differ from
+ * the Console-plane `TrustLevel` — `standard` here vs `verified` there). */
+export declare const SdkBillingTrustLevel: Schema.Literal<["new", "standard", "trusted", "enterprise"]>;
+export type SdkBillingTrustLevel = typeof SdkBillingTrustLevel.Type;
+/** Single plan row exposed to the deployed app's subscription UI. Note the
+ * `monthlyPrice` / `annualPrice` / `lifetimePrice` field names (Console uses
+ * `priceMonthly` / `priceAnnual` / `priceLifetime`). */
+export declare const SdkBillingPlan: Schema.Struct<{
+    id: typeof Schema.String;
+    slug: typeof Schema.String;
+    name: typeof Schema.String;
+    description: Schema.NullOr<typeof Schema.String>;
+    features: Schema.Array$<typeof Schema.String>;
+    monthlyPrice: typeof Schema.Number;
+    annualPrice: typeof Schema.Number;
+    lifetimePrice: Schema.NullOr<typeof Schema.Number>;
+    isPopular: typeof Schema.Boolean;
+    isActive: typeof Schema.Boolean;
+    sortOrder: typeof Schema.Number;
+}>;
+export type SdkBillingPlan = typeof SdkBillingPlan.Type;
+/** `GET /billing/plans` response — flat array (no envelope). */
+export declare const BillingPlansListResponse: Schema.Array$<Schema.Struct<{
+    id: typeof Schema.String;
+    slug: typeof Schema.String;
+    name: typeof Schema.String;
+    description: Schema.NullOr<typeof Schema.String>;
+    features: Schema.Array$<typeof Schema.String>;
+    monthlyPrice: typeof Schema.Number;
+    annualPrice: typeof Schema.Number;
+    lifetimePrice: Schema.NullOr<typeof Schema.Number>;
+    isPopular: typeof Schema.Boolean;
+    isActive: typeof Schema.Boolean;
+    sortOrder: typeof Schema.Number;
+}>>;
+export type BillingPlansListResponse = typeof BillingPlansListResponse.Type;
+/** Resolved subscription for a single end user. */
+export declare const SdkBillingSubscription: Schema.Struct<{
+    id: typeof Schema.String;
+    userId: typeof Schema.String;
+    planId: typeof Schema.String;
+    planSlug: typeof Schema.String;
+    planName: typeof Schema.String;
+    status: Schema.Literal<["active", "canceled", "past_due", "incomplete", "trialing", "paused"]>;
+    interval: Schema.Literal<["monthly", "annual", "lifetime"]>;
+    currentPeriodStart: Schema.NullOr<typeof Schema.String>;
+    currentPeriodEnd: Schema.NullOr<typeof Schema.String>;
+    cancelAtPeriodEnd: typeof Schema.Boolean;
+    trialEnd: Schema.NullOr<typeof Schema.String>;
+}>;
+export type SdkBillingSubscription = typeof SdkBillingSubscription.Type;
+/** `GET /billing/subscription` response — `null` when the user has none. */
+export declare const BillingSubscriptionResponse: Schema.NullOr<Schema.Struct<{
+    id: typeof Schema.String;
+    userId: typeof Schema.String;
+    planId: typeof Schema.String;
+    planSlug: typeof Schema.String;
+    planName: typeof Schema.String;
+    status: Schema.Literal<["active", "canceled", "past_due", "incomplete", "trialing", "paused"]>;
+    interval: Schema.Literal<["monthly", "annual", "lifetime"]>;
+    currentPeriodStart: Schema.NullOr<typeof Schema.String>;
+    currentPeriodEnd: Schema.NullOr<typeof Schema.String>;
+    cancelAtPeriodEnd: typeof Schema.Boolean;
+    trialEnd: Schema.NullOr<typeof Schema.String>;
+}>>;
+export type BillingSubscriptionResponse = typeof BillingSubscriptionResponse.Type;
+/** `POST /billing/checkout` request body. */
+export declare const BillingCheckoutRequest: Schema.Struct<{
+    userId: typeof Schema.String;
+    planSlug: typeof Schema.String;
+    interval: Schema.Literal<["monthly", "annual", "lifetime"]>;
+    successUrl: typeof Schema.String;
+    cancelUrl: typeof Schema.String;
+}>;
+export type BillingCheckoutRequest = typeof BillingCheckoutRequest.Type;
+/** `POST /billing/checkout` response — Stripe session URL + id. */
+export declare const BillingCheckoutResponse: Schema.Struct<{
+    checkoutUrl: Schema.NullOr<typeof Schema.String>;
+    sessionId: typeof Schema.String;
+}>;
+export type BillingCheckoutResponse = typeof BillingCheckoutResponse.Type;
+/** `POST /billing/portal` request body. */
+export declare const BillingPortalRequest: Schema.Struct<{
+    userId: typeof Schema.String;
+    returnUrl: typeof Schema.String;
+}>;
+export type BillingPortalRequest = typeof BillingPortalRequest.Type;
+/** `POST /billing/portal` response — Stripe portal URL. */
+export declare const BillingPortalResponse: Schema.Struct<{
+    portalUrl: typeof Schema.String;
+}>;
+export type BillingPortalResponse = typeof BillingPortalResponse.Type;
+/** Balance envelope — microdollars + pre-formatted display string. */
+export declare const SdkBillingBalanceInfo: Schema.Struct<{
+    current: typeof Schema.Number;
+    currentFormatted: typeof Schema.String;
+}>;
+export type SdkBillingBalanceInfo = typeof SdkBillingBalanceInfo.Type;
+/** Status envelope for the end-user balance response. */
+export declare const SdkBillingStatusInfo: Schema.Struct<{
+    level: Schema.Literal<["healthy", "low", "critical", "exhausted"]>;
+    isHealthy: typeof Schema.Boolean;
+    isLow: typeof Schema.Boolean;
+    alertThreshold: typeof Schema.Number;
+}>;
+export type SdkBillingStatusInfo = typeof SdkBillingStatusInfo.Type;
+/** `GET /billing/balance` response. */
+export declare const BillingBalanceResponse: Schema.Struct<{
+    balance: Schema.Struct<{
+        current: typeof Schema.Number;
+        currentFormatted: typeof Schema.String;
+    }>;
+    status: Schema.Struct<{
+        level: Schema.Literal<["healthy", "low", "critical", "exhausted"]>;
+        isHealthy: typeof Schema.Boolean;
+        isLow: typeof Schema.Boolean;
+        alertThreshold: typeof Schema.Number;
+    }>;
+    billingType: Schema.Literal<["prepaid", "postpaid", "enterprise"]>;
+    trustLevel: Schema.Literal<["new", "standard", "trusted", "enterprise"]>;
+    spendingCap: Schema.NullOr<typeof Schema.Number>;
+    currentMonthSpend: typeof Schema.Number;
+    spendingCapPercent: Schema.NullOr<typeof Schema.Number>;
+    gracePeriodEndsAt: Schema.NullOr<typeof Schema.String>;
+    isAdminOrg: typeof Schema.Boolean;
+}>;
+export type BillingBalanceResponse = typeof BillingBalanceResponse.Type;
+/** Usage period info — currently fixed to `month`. */
+export declare const SdkBillingUsagePeriod: Schema.Struct<{
+    type: Schema.Literal<["month"]>;
+    start: typeof Schema.String;
+    end: typeof Schema.String;
+}>;
+export type SdkBillingUsagePeriod = typeof SdkBillingUsagePeriod.Type;
+/** Per-service usage metrics for the current billing period. */
+export declare const SdkBillingUsageMetrics: Schema.Struct<{
+    aiCostMicrodollars: typeof Schema.Number;
+    storageBytesUsed: typeof Schema.Number;
+    storageEgressBytes: typeof Schema.Number;
+    storageUploads: typeof Schema.Number;
+    dbStorageBytes: typeof Schema.Number;
+    dbComputeSeconds: typeof Schema.Number;
+    emailSentCount: typeof Schema.Number;
+    jobInvocationCount: typeof Schema.Number;
+    cronActiveCount: typeof Schema.Number;
+    notificationsSentCount: typeof Schema.Number;
+    analyticsEventCount: typeof Schema.Number;
+    webhookDeliveryCount: typeof Schema.Number;
+    errorEventCount: typeof Schema.Number;
+    authMau: typeof Schema.Number;
+}>;
+export type SdkBillingUsageMetrics = typeof SdkBillingUsageMetrics.Type;
+/** `GET /billing/usage` response — `metrics` is `null` when no usage data
+ * exists for the period. */
+export declare const BillingUsageResponse: Schema.Struct<{
+    period: Schema.Struct<{
+        type: Schema.Literal<["month"]>;
+        start: typeof Schema.String;
+        end: typeof Schema.String;
+    }>;
+    metrics: Schema.NullOr<Schema.Struct<{
+        aiCostMicrodollars: typeof Schema.Number;
+        storageBytesUsed: typeof Schema.Number;
+        storageEgressBytes: typeof Schema.Number;
+        storageUploads: typeof Schema.Number;
+        dbStorageBytes: typeof Schema.Number;
+        dbComputeSeconds: typeof Schema.Number;
+        emailSentCount: typeof Schema.Number;
+        jobInvocationCount: typeof Schema.Number;
+        cronActiveCount: typeof Schema.Number;
+        notificationsSentCount: typeof Schema.Number;
+        analyticsEventCount: typeof Schema.Number;
+        webhookDeliveryCount: typeof Schema.Number;
+        errorEventCount: typeof Schema.Number;
+        authMau: typeof Schema.Number;
+    }>>;
+}>;
+export type BillingUsageResponse = typeof BillingUsageResponse.Type;
+//# sourceMappingURL=billing.d.ts.map

package/dist/schemas/billing.d.ts.map

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

package/dist/schemas/billing.js

@@ -0,0 +1,147 @@
+/**
+ * Billing — BaaS plane schemas for the deployed-app SDK (`@sylphx/sdk`).
+ * Mirrors the runtime API at `GET /billing/plans`, `/billing/subscription`,
+ * `POST /billing/checkout`, `/billing/portal`, `GET /billing/balance`,
+ * `/billing/usage` (see `apps/runtime/src/server/runtime/schemas/billing.ts`).
+ *
+ * Distinct from `billing-console.ts` (Management plane; Console UI / dev
+ * subscription management), `billing-settings.ts` (org billing configuration),
+ * and `admin-billing.ts` (super-admin cross-org ops). The BaaS surface is the
+ * end-user subscription flow a deployed application exposes to *its* users —
+ * the plan catalog shape, checkout/portal envelope, and balance/usage metrics
+ * all evolve independently of the Console counterparts (different enum
+ * values, different field names, different envelope keys).
+ *
+ * Names are prefixed `SdkBilling*` to disambiguate from the Management-plane
+ * `BillingPlan` / `Subscription` symbols that share the contract barrel.
+ */
+import { Schema } from 'effect';
+// ── Enums ──────────────────────────────────────────────────────────────────
+/** Billing interval for the end-user subscription. */
+export const SdkBillingInterval = Schema.Literal('monthly', 'annual', 'lifetime');
+/** Lifecycle status for a BaaS-plane subscription (note: spells `canceled`,
+ * whereas the Console plane uses `cancelled` — reflects the underlying REST
+ * contract). */
+export const SdkBillingSubscriptionStatus = Schema.Literal('active', 'canceled', 'past_due', 'incomplete', 'trialing', 'paused');
+/** Health status bucket for the end-user balance response. */
+export const SdkBillingStatusLevel = Schema.Literal('healthy', 'low', 'critical', 'exhausted');
+/** Billing type surfaced to the deployed app. */
+export const SdkBillingType = Schema.Literal('prepaid', 'postpaid', 'enterprise');
+/** Trust level surfaced to the deployed app (note literal values differ from
+ * the Console-plane `TrustLevel` — `standard` here vs `verified` there). */
+export const SdkBillingTrustLevel = Schema.Literal('new', 'standard', 'trusted', 'enterprise');
+// ── Plan catalog (`GET /billing/plans`) ───────────────────────────────────
+/** Single plan row exposed to the deployed app's subscription UI. Note the
+ * `monthlyPrice` / `annualPrice` / `lifetimePrice` field names (Console uses
+ * `priceMonthly` / `priceAnnual` / `priceLifetime`). */
+export const SdkBillingPlan = Schema.Struct({
+    id: Schema.String,
+    slug: Schema.String,
+    name: Schema.String,
+    description: Schema.NullOr(Schema.String),
+    features: Schema.Array(Schema.String),
+    monthlyPrice: Schema.Number,
+    annualPrice: Schema.Number,
+    lifetimePrice: Schema.NullOr(Schema.Number),
+    isPopular: Schema.Boolean,
+    isActive: Schema.Boolean,
+    sortOrder: Schema.Number,
+});
+/** `GET /billing/plans` response — flat array (no envelope). */
+export const BillingPlansListResponse = Schema.Array(SdkBillingPlan);
+// ── Subscription (`GET /billing/subscription`) ────────────────────────────
+/** Resolved subscription for a single end user. */
+export const SdkBillingSubscription = Schema.Struct({
+    id: Schema.String,
+    userId: Schema.String,
+    planId: Schema.String,
+    planSlug: Schema.String,
+    planName: Schema.String,
+    status: SdkBillingSubscriptionStatus,
+    interval: SdkBillingInterval,
+    currentPeriodStart: Schema.NullOr(Schema.String),
+    currentPeriodEnd: Schema.NullOr(Schema.String),
+    cancelAtPeriodEnd: Schema.Boolean,
+    trialEnd: Schema.NullOr(Schema.String),
+});
+/** `GET /billing/subscription` response — `null` when the user has none. */
+export const BillingSubscriptionResponse = Schema.NullOr(SdkBillingSubscription);
+// ── Checkout (`POST /billing/checkout`) ───────────────────────────────────
+/** `POST /billing/checkout` request body. */
+export const BillingCheckoutRequest = Schema.Struct({
+    userId: Schema.String,
+    planSlug: Schema.String,
+    interval: SdkBillingInterval,
+    successUrl: Schema.String,
+    cancelUrl: Schema.String,
+});
+/** `POST /billing/checkout` response — Stripe session URL + id. */
+export const BillingCheckoutResponse = Schema.Struct({
+    checkoutUrl: Schema.NullOr(Schema.String),
+    sessionId: Schema.String,
+});
+// ── Portal (`POST /billing/portal`) ───────────────────────────────────────
+/** `POST /billing/portal` request body. */
+export const BillingPortalRequest = Schema.Struct({
+    userId: Schema.String,
+    returnUrl: Schema.String,
+});
+/** `POST /billing/portal` response — Stripe portal URL. */
+export const BillingPortalResponse = Schema.Struct({
+    portalUrl: Schema.String,
+});
+// ── Balance (`GET /billing/balance`) ──────────────────────────────────────
+/** Balance envelope — microdollars + pre-formatted display string. */
+export const SdkBillingBalanceInfo = Schema.Struct({
+    current: Schema.Number,
+    currentFormatted: Schema.String,
+});
+/** Status envelope for the end-user balance response. */
+export const SdkBillingStatusInfo = Schema.Struct({
+    level: SdkBillingStatusLevel,
+    isHealthy: Schema.Boolean,
+    isLow: Schema.Boolean,
+    alertThreshold: Schema.Number,
+});
+/** `GET /billing/balance` response. */
+export const BillingBalanceResponse = Schema.Struct({
+    balance: SdkBillingBalanceInfo,
+    status: SdkBillingStatusInfo,
+    billingType: SdkBillingType,
+    trustLevel: SdkBillingTrustLevel,
+    spendingCap: Schema.NullOr(Schema.Number),
+    currentMonthSpend: Schema.Number,
+    spendingCapPercent: Schema.NullOr(Schema.Number),
+    gracePeriodEndsAt: Schema.NullOr(Schema.String),
+    isAdminOrg: Schema.Boolean,
+});
+// ── Usage (`GET /billing/usage`) ──────────────────────────────────────────
+/** Usage period info — currently fixed to `month`. */
+export const SdkBillingUsagePeriod = Schema.Struct({
+    type: Schema.Literal('month'),
+    start: Schema.String,
+    end: Schema.String,
+});
+/** Per-service usage metrics for the current billing period. */
+export const SdkBillingUsageMetrics = Schema.Struct({
+    aiCostMicrodollars: Schema.Number,
+    storageBytesUsed: Schema.Number,
+    storageEgressBytes: Schema.Number,
+    storageUploads: Schema.Number,
+    dbStorageBytes: Schema.Number,
+    dbComputeSeconds: Schema.Number,
+    emailSentCount: Schema.Number,
+    jobInvocationCount: Schema.Number,
+    cronActiveCount: Schema.Number,
+    notificationsSentCount: Schema.Number,
+    analyticsEventCount: Schema.Number,
+    webhookDeliveryCount: Schema.Number,
+    errorEventCount: Schema.Number,
+    authMau: Schema.Number,
+});
+/** `GET /billing/usage` response — `metrics` is `null` when no usage data
+ * exists for the period. */
+export const BillingUsageResponse = Schema.Struct({
+    period: SdkBillingUsagePeriod,
+    metrics: Schema.NullOr(SdkBillingUsageMetrics),
+});

package/dist/schemas/branch-database.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Branch Database — per-preview-env Postgres branch (P0 Gap #2).
+ *
+ * Schema SSOT for the "branch DB per preview env" feature documented in
+ * `docs/design/branch-db-per-preview.md`. Every branch database is a
+ * short-lived Postgres instance cloned from a source DB (usually prod) via
+ * Rook-Ceph RBD snapshot + CNPG volume bootstrap. Lifecycle is tied to the
+ * preview env — destroying the env GCs the branch.
+ *
+ * Plane: `management` (CRUD). BaaS runtime reads `DATABASE_URL` via secrets.
+ */
+import { Schema } from 'effect';
+/**
+ * Data scope requested at create time — mirrors the CLI `--with-data` flag.
+ *   - `none`     — schema only; truncate all user tables after clone opens.
+ *   - `last-1d`  — keep last 24h of rows (opt-in, heuristic).
+ *   - `last-7d`  — keep last 7 days of rows (opt-in, heuristic).
+ *   - `all`      — full prod data (gated behind org-admin confirm).
+ */
+export declare const BranchDatabaseDataMode: Schema.Literal<["none", "last-1d", "last-7d", "all"]>;
+export type BranchDatabaseDataMode = typeof BranchDatabaseDataMode.Type;
+/**
+ * Lifecycle state mirrored from `branch_databases.status`.
+ *   - `provisioning` — controller has picked it up, snapshot in-flight.
+ *   - `ready`        — Postgres running, connection string available.
+ *   - `destroyed`    — tombstone row; CNPG CR deleted + PVC reclaimed.
+ *   - `degraded`     — provisioning/teardown failure; manual unblock required.
+ */
+export declare const BranchDatabaseStatus: Schema.Literal<["provisioning", "ready", "destroyed", "degraded"]>;
+export type BranchDatabaseStatus = typeof BranchDatabaseStatus.Type;
+/**
+ * Branch database response shape. `connectionString` is null until the branch
+ * reaches `ready` — the API decrypts it on read per-request; never returns
+ * the encrypted-at-rest value.
+ */
+export declare const BranchDatabase: Schema.Struct<{
+    id: typeof Schema.String;
+    projectId: typeof Schema.String;
+    envId: typeof Schema.String;
+    sourceDbId: typeof Schema.String;
+    cnpgClusterName: Schema.NullOr<typeof Schema.String>;
+    connectionString: Schema.NullOr<typeof Schema.String>;
+    dataMode: Schema.Literal<["none", "last-1d", "last-7d", "all"]>;
+    status: Schema.Literal<["provisioning", "ready", "destroyed", "degraded"]>;
+    createdAt: typeof Schema.String;
+    destroyedAt: Schema.NullOr<typeof Schema.String>;
+}>;
+export type BranchDatabase = typeof BranchDatabase.Type;
+/**
+ * `POST /projects/:id/preview-envs/:envId/branch-db`
+ *
+ * `previewEnvId` is redundant with the path `:envId` but we keep it in the
+ * body for API symmetry with other creation flows and to survive URL
+ * rewriting at proxy layers. Server validates both match.
+ */
+export declare const CreateBranchDatabaseInput: Schema.Struct<{
+    previewEnvId: typeof Schema.String;
+    withData: Schema.optional<Schema.Literal<["none", "last-1d", "last-7d", "all"]>>;
+}>;
+export type CreateBranchDatabaseInput = typeof CreateBranchDatabaseInput.Type;
+/** `GET /projects/:id/preview-envs/:envId/branch-db` response. */
+export declare const GetBranchDatabaseResult: Schema.Struct<{
+    id: typeof Schema.String;
+    projectId: typeof Schema.String;
+    envId: typeof Schema.String;
+    sourceDbId: typeof Schema.String;
+    cnpgClusterName: Schema.NullOr<typeof Schema.String>;
+    connectionString: Schema.NullOr<typeof Schema.String>;
+    dataMode: Schema.Literal<["none", "last-1d", "last-7d", "all"]>;
+    status: Schema.Literal<["provisioning", "ready", "destroyed", "degraded"]>;
+    createdAt: typeof Schema.String;
+    destroyedAt: Schema.NullOr<typeof Schema.String>;
+}>;
+export type GetBranchDatabaseResult = typeof GetBranchDatabaseResult.Type;
+/** `GET /preview-envs/branch-dbs` — admin list across a project. */
+export declare const ListBranchDatabasesResult: Schema.Struct<{
+    branches: Schema.Array$<Schema.Struct<{
+        id: typeof Schema.String;
+        projectId: typeof Schema.String;
+        envId: typeof Schema.String;
+        sourceDbId: typeof Schema.String;
+        cnpgClusterName: Schema.NullOr<typeof Schema.String>;
+        connectionString: Schema.NullOr<typeof Schema.String>;
+        dataMode: Schema.Literal<["none", "last-1d", "last-7d", "all"]>;
+        status: Schema.Literal<["provisioning", "ready", "destroyed", "degraded"]>;
+        createdAt: typeof Schema.String;
+        destroyedAt: Schema.NullOr<typeof Schema.String>;
+    }>>;
+}>;
+export type ListBranchDatabasesResult = typeof ListBranchDatabasesResult.Type;
+/** `DELETE /projects/:id/preview-envs/:envId/branch-db` response. */
+export declare const DestroyBranchDatabaseResult: Schema.Struct<{
+    success: typeof Schema.Boolean;
+    branchId: typeof Schema.String;
+    status: Schema.Literal<["provisioning", "ready", "destroyed", "degraded"]>;
+}>;
+export type DestroyBranchDatabaseResult = typeof DestroyBranchDatabaseResult.Type;
+//# sourceMappingURL=branch-database.d.ts.map

package/dist/schemas/branch-database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-database.d.ts","sourceRoot":"","sources":["../../src/schemas/branch-database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,uDAAsD,CAAA;AACzF,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAA;AAEvE;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,oEAAmE,CAAA;AACpG,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AAEnE;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;EAWzB,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB;;;EAGpC,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,OAAO,yBAAyB,CAAC,IAAI,CAAA;AAE7E,kEAAkE;AAClE,eAAO,MAAM,uBAAuB;;;;;;;;;;;EAAiB,CAAA;AACrD,MAAM,MAAM,uBAAuB,GAAG,OAAO,uBAAuB,CAAC,IAAI,CAAA;AAEzE,oEAAoE;AACpE,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;EAEpC,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,OAAO,yBAAyB,CAAC,IAAI,CAAA;AAE7E,qEAAqE;AACrE,eAAO,MAAM,2BAA2B;;;;EAItC,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,OAAO,2BAA2B,CAAC,IAAI,CAAA"}

package/dist/schemas/branch-database.js

@@ -0,0 +1,68 @@
+/**
+ * Branch Database — per-preview-env Postgres branch (P0 Gap #2).
+ *
+ * Schema SSOT for the "branch DB per preview env" feature documented in
+ * `docs/design/branch-db-per-preview.md`. Every branch database is a
+ * short-lived Postgres instance cloned from a source DB (usually prod) via
+ * Rook-Ceph RBD snapshot + CNPG volume bootstrap. Lifecycle is tied to the
+ * preview env — destroying the env GCs the branch.
+ *
+ * Plane: `management` (CRUD). BaaS runtime reads `DATABASE_URL` via secrets.
+ */
+import { Schema } from 'effect';
+/**
+ * Data scope requested at create time — mirrors the CLI `--with-data` flag.
+ *   - `none`     — schema only; truncate all user tables after clone opens.
+ *   - `last-1d`  — keep last 24h of rows (opt-in, heuristic).
+ *   - `last-7d`  — keep last 7 days of rows (opt-in, heuristic).
+ *   - `all`      — full prod data (gated behind org-admin confirm).
+ */
+export const BranchDatabaseDataMode = Schema.Literal('none', 'last-1d', 'last-7d', 'all');
+/**
+ * Lifecycle state mirrored from `branch_databases.status`.
+ *   - `provisioning` — controller has picked it up, snapshot in-flight.
+ *   - `ready`        — Postgres running, connection string available.
+ *   - `destroyed`    — tombstone row; CNPG CR deleted + PVC reclaimed.
+ *   - `degraded`     — provisioning/teardown failure; manual unblock required.
+ */
+export const BranchDatabaseStatus = Schema.Literal('provisioning', 'ready', 'destroyed', 'degraded');
+/**
+ * Branch database response shape. `connectionString` is null until the branch
+ * reaches `ready` — the API decrypts it on read per-request; never returns
+ * the encrypted-at-rest value.
+ */
+export const BranchDatabase = Schema.Struct({
+    id: Schema.String,
+    projectId: Schema.String,
+    envId: Schema.String,
+    sourceDbId: Schema.String,
+    cnpgClusterName: Schema.NullOr(Schema.String),
+    connectionString: Schema.NullOr(Schema.String),
+    dataMode: BranchDatabaseDataMode,
+    status: BranchDatabaseStatus,
+    createdAt: Schema.String,
+    destroyedAt: Schema.NullOr(Schema.String),
+});
+/**
+ * `POST /projects/:id/preview-envs/:envId/branch-db`
+ *
+ * `previewEnvId` is redundant with the path `:envId` but we keep it in the
+ * body for API symmetry with other creation flows and to survive URL
+ * rewriting at proxy layers. Server validates both match.
+ */
+export const CreateBranchDatabaseInput = Schema.Struct({
+    previewEnvId: Schema.String,
+    withData: Schema.optional(BranchDatabaseDataMode),
+});
+/** `GET /projects/:id/preview-envs/:envId/branch-db` response. */
+export const GetBranchDatabaseResult = BranchDatabase;
+/** `GET /preview-envs/branch-dbs` — admin list across a project. */
+export const ListBranchDatabasesResult = Schema.Struct({
+    branches: Schema.Array(BranchDatabase),
+});
+/** `DELETE /projects/:id/preview-envs/:envId/branch-db` response. */
+export const DestroyBranchDatabaseResult = Schema.Struct({
+    success: Schema.Boolean,
+    branchId: Schema.String,
+    status: BranchDatabaseStatus,
+});

package/dist/schemas/challenge.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Challenge — step-up authentication (Clerk-style reverification) for
+ * sensitive Console operations. Mirrors the wire shapes served at
+ * `/challenge/*` in `apps/api/src/server/platform/routes/challenge.ts`.
+ *
+ * The operation whitelist is the SSOT in
+ * `@sylphx/core/features/auth/lib/challenge` (`OPERATION_REQUIREMENTS`).
+ * We intentionally type `operation` as `Schema.String` here so a new
+ * operation added to core does not require a corresponding contract bump —
+ * the runtime service rejects unknown operations.
+ */
+import { Schema } from 'effect';
+export declare const ChallengeLevel: Schema.Literal<["strict_mfa", "strict", "moderate", "lax"]>;
+export type ChallengeLevel = typeof ChallengeLevel.Type;
+export declare const IdentityMethod: Schema.Literal<["password", "email"]>;
+export type IdentityMethod = typeof IdentityMethod.Type;
+export declare const MfaMethod: Schema.Literal<["totp", "backup"]>;
+export type MfaMethod = typeof MfaMethod.Type;
+/** Query for `/challenge/required` — only carries the operation name. */
+export declare const ChallengeRequiredQuery: Schema.Struct<{
+    operation: typeof Schema.String;
+}>;
+export type ChallengeRequiredQuery = typeof ChallengeRequiredQuery.Type;
+export declare const ChallengeIdentityStatus: Schema.Struct<{
+    verified: typeof Schema.Boolean;
+    expiresAt: Schema.NullOr<typeof Schema.String>;
+    method: Schema.NullOr<Schema.Literal<["password", "email"]>>;
+}>;
+export type ChallengeIdentityStatus = typeof ChallengeIdentityStatus.Type;
+export declare const ChallengeMfaStatus: Schema.Struct<{
+    verified: typeof Schema.Boolean;
+    expiresAt: Schema.NullOr<typeof Schema.String>;
+    method: Schema.NullOr<Schema.Literal<["totp", "backup"]>>;
+}>;
+export type ChallengeMfaStatus = typeof ChallengeMfaStatus.Type;
+export declare const ChallengeAvailableMethods: Schema.Struct<{
+    identity: Schema.Array$<Schema.Literal<["password", "email"]>>;
+    mfa: Schema.Array$<Schema.Literal<["totp", "backup"]>>;
+}>;
+export type ChallengeAvailableMethods = typeof ChallengeAvailableMethods.Type;
+export declare const ChallengeUserCapabilities: Schema.Struct<{
+    hasPassword: typeof Schema.Boolean;
+    has2FA: typeof Schema.Boolean;
+    maskedEmail: typeof Schema.String;
+}>;
+export type ChallengeUserCapabilities = typeof ChallengeUserCapabilities.Type;
+export declare const ChallengeRequiredResult: Schema.Struct<{
+    required: typeof Schema.Boolean;
+    level: Schema.Literal<["strict_mfa", "strict", "moderate", "lax"]>;
+    identity: Schema.Struct<{
+        verified: typeof Schema.Boolean;
+        expiresAt: Schema.NullOr<typeof Schema.String>;
+        method: Schema.NullOr<Schema.Literal<["password", "email"]>>;
+    }>;
+    mfa: Schema.Struct<{
+        verified: typeof Schema.Boolean;
+        expiresAt: Schema.NullOr<typeof Schema.String>;
+        method: Schema.NullOr<Schema.Literal<["totp", "backup"]>>;
+    }>;
+    methods: Schema.Struct<{
+        identity: Schema.Array$<Schema.Literal<["password", "email"]>>;
+        mfa: Schema.Array$<Schema.Literal<["totp", "backup"]>>;
+    }>;
+    user: Schema.Struct<{
+        hasPassword: typeof Schema.Boolean;
+        has2FA: typeof Schema.Boolean;
+        maskedEmail: typeof Schema.String;
+    }>;
+}>;
+export type ChallengeRequiredResult = typeof ChallengeRequiredResult.Type;
+export declare const SendChallengeCodeResult: Schema.Struct<{
+    sent: typeof Schema.Boolean;
+    expiresAt: typeof Schema.String;
+    maskedEmail: typeof Schema.String;
+}>;
+export type SendChallengeCodeResult = typeof SendChallengeCodeResult.Type;
+export declare const VerifyIdentityInput: Schema.Struct<{
+    method: Schema.Literal<["password", "email"]>;
+    value: typeof Schema.String;
+}>;
+export type VerifyIdentityInput = typeof VerifyIdentityInput.Type;
+export declare const VerifyMfaInput: Schema.Struct<{
+    method: Schema.Literal<["totp", "backup"]>;
+    value: typeof Schema.String;
+}>;
+export type VerifyMfaInput = typeof VerifyMfaInput.Type;
+/** Identity + MFA verify share the same response shape. */
+export declare const VerifyChallengeResult: Schema.Struct<{
+    verified: typeof Schema.Boolean;
+    method: typeof Schema.String;
+}>;
+export type VerifyChallengeResult = typeof VerifyChallengeResult.Type;
+export declare const ChallengeStatusResult: Schema.Struct<{
+    identity: Schema.Struct<{
+        verifiedAt: Schema.NullOr<typeof Schema.String>;
+        method: Schema.NullOr<Schema.Literal<["password", "email"]>>;
+    }>;
+    mfa: Schema.Struct<{
+        verifiedAt: Schema.NullOr<typeof Schema.String>;
+        method: Schema.NullOr<Schema.Literal<["totp", "backup"]>>;
+    }>;
+}>;
+export type ChallengeStatusResult = typeof ChallengeStatusResult.Type;
+//# sourceMappingURL=challenge.d.ts.map

package/dist/schemas/challenge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"challenge.d.ts","sourceRoot":"","sources":["../../src/schemas/challenge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B,eAAO,MAAM,cAAc,6DAA4D,CAAA;AACvF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD,eAAO,MAAM,cAAc,uCAAsC,CAAA;AACjE,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD,eAAO,MAAM,SAAS,oCAAmC,CAAA;AACzD,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAA;AAE7C,yEAAyE;AACzE,eAAO,MAAM,sBAAsB;;EAEjC,CAAA;AACF,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAA;AAEvE,eAAO,MAAM,uBAAuB;;;;EAIlC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,OAAO,uBAAuB,CAAC,IAAI,CAAA;AAEzE,eAAO,MAAM,kBAAkB;;;;EAI7B,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAE/D,eAAO,MAAM,yBAAyB;;;EAGpC,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,OAAO,yBAAyB,CAAC,IAAI,CAAA;AAE7E,eAAO,MAAM,yBAAyB;;;;EAIpC,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,OAAO,yBAAyB,CAAC,IAAI,CAAA;AAE7E,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;EAOlC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,OAAO,uBAAuB,CAAC,IAAI,CAAA;AAEzE,eAAO,MAAM,uBAAuB;;;;EAIlC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,OAAO,uBAAuB,CAAC,IAAI,CAAA;AAEzE,eAAO,MAAM,mBAAmB;;;EAG9B,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC,IAAI,CAAA;AAEjE,eAAO,MAAM,cAAc;;;EAGzB,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD,2DAA2D;AAC3D,eAAO,MAAM,qBAAqB;;;EAGhC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,OAAO,qBAAqB,CAAC,IAAI,CAAA;AAErE,eAAO,MAAM,qBAAqB;;;;;;;;;EAShC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,OAAO,qBAAqB,CAAC,IAAI,CAAA"}