@forgedevv/shared 0.0.0-stage → 0.2.0

package/dist/api.js

@@ -0,0 +1,307 @@
+import { z } from 'zod';
+import { JobStatus } from './jobs.js';
+import { PaymentKind, PaymentStatus } from './db.js';
+import { LaunchpadSpec, SolanaAddress } from './spec.js';
+/*
+ * Request/response schemas of the apps/web API (docs/INTERFACES.md §6) and of the internal
+ * builder -> signer API (§7). Request bodies are strict (unknown keys are rejected); responses
+ * strip unknown keys.
+ */
+// ---------------------------------------------------------------------------
+// Primitives
+// ---------------------------------------------------------------------------
+/** Lamports serialized as a decimal string (bigint). 1 SOL = 1_000_000_000 lamports. */
+export const Lamports = z
+    .string()
+    .regex(/^\d+$/, { error: 'Lamports must be a decimal integer string' });
+/** Raw token amount (smallest units) serialized as a decimal string. */
+export const RawTokenAmount = z.string().regex(/^\d+$/);
+/** Base58 ed25519 signature (transaction signature or signed message). */
+export const Base58Signature = z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{64,88}$/, {
+    error: 'Invalid base58 signature',
+});
+/** Serialized transaction, base64 encoded. */
+export const Base64Transaction = z.base64().min(1);
+export const Uuid = z.uuid();
+/** ISO 8601 date-time (UTC `Z` or with an offset). */
+export const IsoDateTime = z.iso.datetime({ offset: true });
+/** Path params of routes with `:id`. */
+export const RouteIdParams = z.strictObject({ id: Uuid });
+// ---------------------------------------------------------------------------
+// apps/web routes (§6)
+// ---------------------------------------------------------------------------
+export const WEB_API_ROUTES = {
+    authNonce: { method: 'POST', path: '/api/auth/nonce' },
+    authVerify: { method: 'POST', path: '/api/auth/verify' },
+    authSession: { method: 'GET', path: '/api/auth/session' },
+    authLogout: { method: 'POST', path: '/api/auth/logout' },
+    authSupabaseToken: { method: 'GET', path: '/api/auth/supabase-token' },
+    gating: { method: 'GET', path: '/api/gating' },
+    flags: { method: 'GET', path: '/api/flags' },
+    chat: { method: 'POST', path: '/api/chat' },
+    specConfirm: { method: 'POST', path: '/api/spec/confirm' },
+    launchpadModifications: { method: 'POST', path: '/api/launchpads/:id/modifications' },
+    paymentsQuote: { method: 'POST', path: '/api/payments/quote' },
+    paymentsConfirm: { method: 'POST', path: '/api/payments/confirm' },
+    jobApprove: { method: 'POST', path: '/api/jobs/:id/approve' },
+    ownerTransactionGet: { method: 'GET', path: '/api/jobs/:id/owner-transaction' },
+    ownerTransactionSubmit: { method: 'POST', path: '/api/jobs/:id/owner-transaction' },
+    jobGet: { method: 'GET', path: '/api/jobs/:id' },
+    launchpadsList: { method: 'GET', path: '/api/launchpads' },
+    launchpadGet: { method: 'GET', path: '/api/launchpads/:id' },
+    claimTransaction: { method: 'GET', path: '/api/launchpads/:id/claim-transaction' },
+    launchpadReactivate: { method: 'POST', path: '/api/launchpads/:id/reactivate' },
+    launchpadRetry: { method: 'POST', path: '/api/launchpads/:id/retry' },
+    rpc: { method: 'POST', path: '/api/rpc' },
+};
+// POST /api/auth/nonce
+export const AuthNonceRequest = z.strictObject({ wallet: SolanaAddress });
+/**
+ * `nonce` is an opaque server-signed token (stateless). `message` is the exact text the wallet
+ * must sign; the client never builds it. The token is also set as an HttpOnly cookie.
+ */
+export const AuthNonceResponse = z.object({
+    nonce: z.string().min(1),
+    message: z.string().min(1),
+    expiresAt: z.string().min(1),
+});
+// POST /api/auth/verify — signature of the message containing the nonce
+export const AuthVerifyRequest = z.strictObject({
+    wallet: SolanaAddress,
+    signature: Base58Signature,
+    /** The token returned by /api/auth/nonce; optional because it is also sent as a cookie. */
+    nonce: z.string().min(1).optional(),
+});
+/** The session. */
+export const AuthVerifyResponse = z.object({ wallet: SolanaAddress });
+// POST /api/auth/logout
+export const AuthLogoutResponse = z.object({ ok: z.literal(true) });
+// GET /api/auth/supabase-token — short-lived JWT for Supabase RLS / Realtime (claim `wallet`)
+export const SupabaseTokenResponse = z.object({
+    accessToken: z.string().min(1),
+    expiresAt: z.string().min(1),
+});
+export const Session = AuthVerifyResponse;
+// GET /api/gating — FORGE_GATING_AMOUNT of mint FORGE_MINT. Without FORGE_MINT, gating is
+// disabled: `enabled: false` and `ok: true`.
+export const GatingResponse = z.object({
+    ok: z.boolean(),
+    /** Required raw amount (smallest units). */
+    required: RawTokenAmount,
+    /** Wallet raw balance (smallest units). */
+    balance: RawTokenAmount,
+    enabled: z.boolean(),
+    /** Decimals of the $FORGE mint, read on-chain with the balance; absent when nothing was read. */
+    decimals: z.number().int().min(0).max(18).optional(),
+});
+// GET /api/flags — public kill-switch state needed by the UI
+export const FlagsResponse = z.object({ signupsPaused: z.boolean() });
+// POST /api/chat — text/event-stream of ChatStreamEvent (web-client.ts); always starts with
+// { type: 'conversation', conversationId } and ends with { type: 'done' }.
+export const ChatRequest = z.strictObject({
+    conversationId: Uuid.optional(),
+    /** Set for a modification of an existing launchpad. */
+    launchpadId: Uuid.optional(),
+    message: z.string().min(1),
+});
+/** Payload of the first stream event. */
+export const ChatResponse = z.object({ conversationId: Uuid });
+// POST /api/spec/confirm
+export const SpecConfirmRequest = z.strictObject({ conversationId: Uuid, spec: LaunchpadSpec });
+export const SpecConfirmResponse = z.object({ launchpadId: Uuid, jobId: Uuid });
+// POST /api/launchpads/:id/modifications
+export const LaunchpadModificationRequest = z.strictObject({
+    conversationId: Uuid,
+    request: z.string().min(1),
+});
+export const LaunchpadModificationResponse = z.object({ jobId: Uuid });
+/*
+ * POST /api/launchpads/:id/retry (no body) — "start again": a draft whose creation was refunded
+ * gets a new `create_launchpad` job in `spec_ready`, built from the launchpad's stored spec (same
+ * name and subdomain). Idempotent: while that job awaits payment, the same job id is returned.
+ */
+export const LaunchpadRetryResponse = z.object({ jobId: Uuid });
+// POST /api/payments/quote
+export const PaymentsQuoteRequest = z.strictObject({ jobId: Uuid, kind: PaymentKind });
+/** Quote as seen by the UI (docs/frontend/CONTRACT.md). */
+export const Quote = z.object({
+    paymentId: Uuid,
+    kind: PaymentKind,
+    lamports: Lamports,
+    usdAmount: z.number().nonnegative(),
+    expiresAt: IsoDateTime,
+});
+/**
+ * `transaction` is the unsigned payment transaction (base64). It is null when lamports = "0"
+ * (an included modification remains and the job goes straight to `paid`).
+ */
+export const PaymentsQuoteResponse = Quote.extend({ transaction: Base64Transaction.nullable() });
+// POST /api/payments/confirm
+export const PaymentsConfirmRequest = z.strictObject({
+    paymentId: Uuid,
+    signature: Base58Signature,
+});
+export const PaymentsConfirmResponse = z.object({ status: PaymentStatus });
+// POST /api/jobs/:id/approve (no body)
+export const JobApproveResponse = z.object({ status: JobStatus });
+/** Summary shown before the client signs the launch transaction. */
+export const OwnerTransactionSummary = z.object({
+    coinName: z.string(),
+    coinSymbol: z.string(),
+    firstBuyLamports: Lamports,
+    /** Everything the owner pays besides the first buy: network fee, rents, Metaplex fee, pool creation fee. */
+    estimatedNetworkFeeLamports: Lamports,
+    ownerWallet: SolanaAddress,
+    /**
+     * Balance the owner's wallet must hold before signing: first buy + everything above + the rent
+     * of the temporary WSOL account (created and closed within the transaction, so refunded, but
+     * held while it runs). Optional: absent when the server cannot compute it; older readers ignore it.
+     */
+    ownerRequiredBalanceLamports: Lamports.optional(),
+});
+/** Absolute https URL (the launchpad coin metadata URI). Kept exactly as sent (no normalization). */
+export const HttpsUrl = z.url({ protocol: /^https$/, error: 'Must be an https URL' });
+/**
+ * The accounts of the launch transaction, pinned by the browser (`verifyLaunchCoinTransaction` of
+ * @forge/core) before the owner signs: the launchpad coin config and mint (launchpad row), the
+ * FORGE creator wallet that creates the pool and holds the durable nonce, the durable nonce
+ * account, and the coin metadata URI written by the pool creation.
+ */
+export const OwnerTransactionLaunch = z.object({
+    config: SolanaAddress,
+    mint: SolanaAddress,
+    creator: SolanaAddress,
+    nonceAccount: SolanaAddress,
+    metadataUri: HttpsUrl,
+});
+// GET /api/jobs/:id/owner-transaction — launch transaction partially signed by FORGE
+export const OwnerTransactionGetResponse = z.object({
+    transaction: Base64Transaction,
+    /** Shown to the client before signing (INTERFACES §6). */
+    summary: OwnerTransactionSummary,
+    /** Whether the summary comes from a simulation of the exact message; when not `ok`, it is a lower bound. */
+    simulation: z.enum(['ok', 'failed', 'unavailable']).optional(),
+    /**
+     * The launch accounts the transaction must use. Optional in the schema so that older readers and
+     * writers still parse; the browser client refuses to sign a launch without it (fail closed).
+     */
+    launch: OwnerTransactionLaunch.optional(),
+});
+// POST /api/jobs/:id/owner-transaction
+export const OwnerTransactionSubmitRequest = z.strictObject({
+    signedTransaction: Base64Transaction,
+});
+export const OwnerTransactionSubmitResponse = z.object({ signature: Base58Signature });
+// GET /api/launchpads/:id/claim-transaction — client partner fee claim
+export const ClaimTransactionSummary = z.object({
+    /** The pool this transaction claims (one pool per transaction). */
+    pool: SolanaAddress,
+    /** Partner trading fees claimed by this transaction. */
+    tradingFeesLamports: Lamports,
+    /** Partner pool creation fee claimed by this transaction (0 when none). */
+    poolCreationFeeLamports: Lamports,
+    /** What the owner pays to claim: network fee and any account rent. */
+    ownerCostLamports: Lamports,
+    /** Pools still holding claimable fees after this one. */
+    remainingPools: z.number().int().nonnegative(),
+});
+export const ClaimTransactionResponse = z.object({
+    transaction: Base64Transaction,
+    summary: ClaimTransactionSummary.optional(),
+});
+// POST /api/rpc — Helius relay (method allow-list and per-IP rate limit enforced by apps/web)
+const JsonRpcId = z.union([z.string(), z.number(), z.null()]);
+export const RpcRequest = z.strictObject({
+    jsonrpc: z.literal('2.0'),
+    id: JsonRpcId,
+    method: z.string().min(1),
+    params: z.union([z.array(z.unknown()), z.record(z.string(), z.unknown())]).optional(),
+});
+export const RpcResponse = z.object({
+    jsonrpc: z.literal('2.0'),
+    id: JsonRpcId,
+    result: z.unknown().optional(),
+    error: z
+        .object({ code: z.number().int(), message: z.string(), data: z.unknown().optional() })
+        .optional(),
+});
+// ---------------------------------------------------------------------------
+// Internal builder -> signer API (§7)
+// ---------------------------------------------------------------------------
+/** Lowercase hex HMAC-SHA256 computed with SIGNER_HMAC_SECRET over `signerSignedPayload(...)`. */
+export const SIGNER_SIGNATURE_HEADER = 'X-Forge-Signature';
+/** Unix time in seconds, as a decimal string. */
+export const SIGNER_TIMESTAMP_HEADER = 'X-Forge-Timestamp';
+/**
+ * 16 random bytes as 32 lowercase hex characters, fresh for every request (and every retry). The
+ * signer accepts a nonce once within the clock-skew window.
+ */
+export const SIGNER_NONCE_HEADER = 'X-Forge-Nonce';
+/** Requests whose timestamp differs from the signer clock by more than this are rejected. */
+export const SIGNER_MAX_CLOCK_SKEW_SECONDS = 60;
+/** First line of the signed string. Any change to its layout gets a new tag. */
+export const SIGNER_SIGNATURE_VERSION = 'forge-signer-v2';
+const SIGNED_FIELD_FORMATS = {
+    method: /^[A-Z]{1,16}$/,
+    // Origin-form target: printable ASCII, no space, no control character.
+    path: /^\/[\x21-\x7e]{0,2047}$/,
+    timestamp: /^[0-9]{1,12}$/,
+    nonce: /^[0-9a-f]{32}$/,
+    bodySha256: /^[0-9a-f]{64}$/,
+};
+/**
+ * Exact string fed to HMAC-SHA256, one field per line, in this order:
+ *
+ *   forge-signer-v2\n<METHOD>\n<path?query>\n<timestamp>\n<nonce>\n<body sha256>
+ *
+ * Every field has a strict format that excludes the line feed, and the field count is fixed, so
+ * the string decodes to exactly one tuple: a signature made for one method, route, query, time,
+ * nonce or body is worth nothing for any other. Throws on a field outside its format, so neither
+ * side can sign or check an ambiguous string.
+ */
+export function signerSignedPayload(fields) {
+    for (const key of Object.keys(SIGNED_FIELD_FORMATS)) {
+        const value = fields[key];
+        if (typeof value !== 'string' || !SIGNED_FIELD_FORMATS[key].test(value)) {
+            throw new TypeError(`signer signed payload: invalid ${key}`);
+        }
+    }
+    return [
+        SIGNER_SIGNATURE_VERSION,
+        fields.method,
+        fields.path,
+        fields.timestamp,
+        fields.nonce,
+        fields.bodySha256,
+    ].join('\n');
+}
+export const SIGNER_ROUTES = {
+    configs: { method: 'POST', path: '/v1/configs' },
+    launchCoinPrepare: { method: 'POST', path: '/v1/launch-coin/prepare' },
+    health: { method: 'GET', path: '/v1/health' },
+};
+/*
+ * The signer never takes an address or an amount from the request: it re-reads everything in
+ * Supabase. Requests are therefore strict and carry only the job id. Both routes are idempotent.
+ */
+// POST /v1/configs
+export const SignerConfigsRequest = z.strictObject({ jobId: Uuid });
+export const SignerConfigsResponse = z.object({
+    launchpadConfig: SolanaAddress,
+    launchpadCoinConfig: SolanaAddress,
+});
+// POST /v1/launch-coin/prepare — durable-nonce transaction signed by the creator wallet
+export const SignerLaunchPrepareRequest = z.strictObject({ jobId: Uuid });
+export const SignerLaunchPrepareResponse = z.object({
+    partiallySignedTx: Base64Transaction,
+    mint: SolanaAddress,
+    summary: OwnerTransactionSummary.optional(),
+    details: z.record(z.string(), z.unknown()).optional(),
+});
+// GET /v1/health
+export const SignerHealthResponse = z.object({
+    ok: z.boolean(),
+    cluster: z.string().optional(),
+    uptimeSeconds: z.number().optional(),
+    jobs: z.record(z.string(), z.unknown()).optional(),
+});

package/dist/constants.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Business constants shared by every FORGE app (docs/INTERFACES.md §1).
+ * Percentages are expressed in basis points (bps) unless the name says `Pct`.
+ */
+export declare const PRICING: {
+    readonly creationUsd: 33;
+    readonly modificationUsd: 5.5;
+    readonly includedModifications: 2;
+    readonly maxAttemptsBeforeRefund: 2;
+    readonly quoteValiditySeconds: 120;
+};
+export declare const FEES: {
+    /** Our fee on our own buy button (before graduation). */
+    readonly platformFeeBps: 30;
+    /** After graduation; Jupiter keeps 20 % of it. */
+    readonly jupiterIntegratorFeeBps: 30;
+    /** FORGE creator share on the coin of every launchpad. */
+    readonly forgeCreatorSharePct: 25;
+};
+export declare const CLIENT_BOUNDS: {
+    /** Trading fee range offered to clients. */
+    readonly tradingFeeBps: {
+        readonly min: 50;
+        readonly max: 200;
+    };
+    readonly coinCreatorSharePct: {
+        readonly min: 0;
+        readonly max: 50;
+        readonly default: 25;
+    };
+    /**
+     * Coin creation fee set by the client: 0 (no fee) or between 0.001 and 1 SOL
+     * (0.001 SOL = MIN_POOL_CREATION_FEE of the SDK). Whether the SDK accepts 0 must be
+     * confirmed by devnet test 1; otherwise the minimum becomes 0.001.
+     */
+    readonly poolCreationFeeSol: {
+        readonly min: 0.001;
+        readonly max: 1;
+        readonly allowZero: true;
+    };
+    /** Imposed (Meteora migration bots). */
+    readonly migrationThresholdSol: 10;
+};
+export declare const OPS: {
+    readonly dormantDaysBeforeSleep: 30;
+    readonly claimIntervalHours: 24;
+    readonly agentBudgetUsdPerJob: 15;
+    readonly agentTimeoutMinutes: 30;
+    /** Past this delay, an active job with no news is considered crashed. */
+    readonly jobLockStaleMinutes: 45;
+};
+/** 1 SOL = 1_000_000_000 lamports. */
+export declare const LAMPORTS_PER_SOL = 1000000000;

package/dist/constants.js

@@ -0,0 +1,42 @@
+/**
+ * Business constants shared by every FORGE app (docs/INTERFACES.md §1).
+ * Percentages are expressed in basis points (bps) unless the name says `Pct`.
+ */
+export const PRICING = {
+    creationUsd: 33,
+    modificationUsd: 5.5,
+    includedModifications: 2,
+    maxAttemptsBeforeRefund: 2,
+    quoteValiditySeconds: 120,
+};
+export const FEES = {
+    /** Our fee on our own buy button (before graduation). */
+    platformFeeBps: 30,
+    /** After graduation; Jupiter keeps 20 % of it. */
+    jupiterIntegratorFeeBps: 30,
+    /** FORGE creator share on the coin of every launchpad. */
+    forgeCreatorSharePct: 25,
+};
+export const CLIENT_BOUNDS = {
+    /** Trading fee range offered to clients. */
+    tradingFeeBps: { min: 50, max: 200 },
+    coinCreatorSharePct: { min: 0, max: 50, default: 25 },
+    /**
+     * Coin creation fee set by the client: 0 (no fee) or between 0.001 and 1 SOL
+     * (0.001 SOL = MIN_POOL_CREATION_FEE of the SDK). Whether the SDK accepts 0 must be
+     * confirmed by devnet test 1; otherwise the minimum becomes 0.001.
+     */
+    poolCreationFeeSol: { min: 0.001, max: 1, allowZero: true },
+    /** Imposed (Meteora migration bots). */
+    migrationThresholdSol: 10,
+};
+export const OPS = {
+    dormantDaysBeforeSleep: 30,
+    claimIntervalHours: 24,
+    agentBudgetUsdPerJob: 15,
+    agentTimeoutMinutes: 30,
+    /** Past this delay, an active job with no news is considered crashed. */
+    jobLockStaleMinutes: 45,
+};
+/** 1 SOL = 1_000_000_000 lamports. */
+export const LAMPORTS_PER_SOL = 1_000_000_000;

package/dist/db.d.ts

@@ -0,0 +1,189 @@
+import { z } from 'zod';
+import type { FailedStage, JobStatus, JobType } from './jobs.js';
+import { type LaunchpadSpec } from './spec.js';
+/**
+ * Row types of the Supabase tables (docs/INTERFACES.md §5). Column names are kept in snake_case.
+ * Nullability mirrors the SQL exactly: a column without `not null` is typed `| null`, even when
+ * it has a default.
+ */
+export declare const LaunchpadStatus: z.ZodEnum<{
+    live: "live";
+    draft: "draft";
+    sleeping: "sleeping";
+    disabled: "disabled";
+}>;
+export type LaunchpadStatus = z.infer<typeof LaunchpadStatus>;
+/**
+ * Shape of `launchpads.site_host` (migration 0011 holds the same CHECK): a lowercase DNS name
+ * without scheme, port, path or trailing dot. Under `vercel.app` (Vercel's production aliases),
+ * exactly one label; `vercel.app` itself is never a site host.
+ */
+export declare function isSiteHost(value: unknown): value is string;
+/** A site host on `vercel.app` (`<one label>.vercel.app`). */
+export declare function isVercelAppHost(value: unknown): value is string;
+/**
+ * The recorded `site_host` of the launchpad `slug`, when a reader may trust it (relay origins,
+ * upload `auth.host`, links to the site): exactly `<one label>.vercel.app` (an alias of the
+ * launchpad's own Vercel project, checked by the builder before it records one), or exactly
+ * `<slug>.<clientsDomain>`. Any other host, however well formed (another domain, the subdomain of
+ * another launchpad), is ignored: null. `clientsDomain` is lowercase (readClientsDomain).
+ */
+export declare function trustedSiteHost(siteHost: unknown, slug: string, clientsDomain: string | null): string | null;
+export declare const SiteHost: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+export declare const PaymentStatus: z.ZodEnum<{
+    refunded: "refunded";
+    quoted: "quoted";
+    confirmed: "confirmed";
+    expired: "expired";
+}>;
+export type PaymentStatus = z.infer<typeof PaymentStatus>;
+export declare const PaymentKind: z.ZodEnum<{
+    creation: "creation";
+    modification: "modification";
+}>;
+export type PaymentKind = z.infer<typeof PaymentKind>;
+export declare const ChatRole: z.ZodEnum<{
+    user: "user";
+    assistant: "assistant";
+    system: "system";
+}>;
+export type ChatRole = z.infer<typeof ChatRole>;
+/** Kill switches. */
+export declare const FlagKey: z.ZodEnum<{
+    deploys_paused: "deploys_paused";
+    buyback_paused: "buyback_paused";
+    signups_paused: "signups_paused";
+    claims_paused: "claims_paused";
+    cashbox_sweep_paused: "cashbox_sweep_paused";
+    refunds_paused: "refunds_paused";
+    jupiter_claims_paused: "jupiter_claims_paused";
+}>;
+export type FlagKey = z.infer<typeof FlagKey>;
+/** ISO 8601 timestamp as returned by PostgREST for `timestamptz`. */
+export type Timestamptz = string;
+/**
+ * Postgres `bigint` / `numeric`: PostgREST may return a JSON number or a string. Convert with
+ * `BigInt(String(value))` for lamports, never with floating point math.
+ */
+export type DbBigint = number | string;
+export type DbNumeric = number | string;
+export interface UserRow {
+    wallet: string;
+    created_at: Timestamptz | null;
+}
+export interface LaunchpadRow {
+    id: string;
+    owner_wallet: string;
+    slug: string;
+    spec: LaunchpadSpec;
+    github_repo: string | null;
+    vercel_project_id: string | null;
+    /** Meteora config address. */
+    launchpad_config: string | null;
+    launchpad_coin_config: string | null;
+    launchpad_coin_mint: string | null;
+    /** Identifier of the creator wallet inside the signer (never the key). */
+    creator_wallet_ref: string | null;
+    included_modifications_left: number | null;
+    status: LaunchpadStatus;
+    last_trade_at: Timestamptz | null;
+    created_at: Timestamptz | null;
+    /**
+     * Exact production host of the client site (`SiteHost`), recorded by the builder from the Vercel
+     * API when the site goes live: the verified `<slug>.<CLIENTS_DOMAIN>`, else a `*.vercel.app`
+     * alias of the launchpad's own Vercel project. Trusted by exact match only (RPC relay origins,
+     * coin uploads, site links). Null until recorded (migration 0011).
+     */
+    site_host: string | null;
+}
+/**
+ * `jobs.owner_tx_details` (jsonb): the public accounts of the launch transaction stored in
+ * `jobs.owner_tx`, as the signer reported them (`details` of `POST /v1/launch-coin/prepare`). The
+ * builder writes it in the same update as `owner_tx`; apps/web pins these accounts when it checks
+ * the stored transaction (`verifyLaunchCoinTransaction` of @forge/core) and hands them to the
+ * browser (`OwnerTransactionLaunch`), instead of reading them back from the transaction.
+ * `config` is the launchpad coin config. Null on rows written before migration 0009.
+ */
+export declare const JobOwnerTxDetails: z.ZodObject<{
+    config: z.ZodString;
+    pool: z.ZodString;
+    creator: z.ZodString;
+    nonceAccount: z.ZodString;
+    metadataUri: z.ZodURL;
+}, z.core.$strip>;
+export type JobOwnerTxDetails = z.infer<typeof JobOwnerTxDetails>;
+export interface JobRow {
+    id: string;
+    launchpad_id: string;
+    type: JobType;
+    status: JobStatus;
+    /** Build attempts only. */
+    attempts: number;
+    /** Set when status = 'failed'. */
+    failed_stage: FailedStage | null;
+    /** Client request (modifications). */
+    request: string | null;
+    preview_url: string | null;
+    /** Partially signed launch transaction (base64) with a durable nonce. */
+    owner_tx: string | null;
+    /** Launch accounts of `owner_tx` (jsonb, validate with `JobOwnerTxDetails` when reading). */
+    owner_tx_details: JobOwnerTxDetails | null;
+    error: string | null;
+    api_cost_usd: DbNumeric | null;
+    /** Id of the worker holding the job. */
+    locked_by: string | null;
+    locked_at: Timestamptz | null;
+    created_at: Timestamptz | null;
+    updated_at: Timestamptz | null;
+}
+export interface PaymentRow {
+    id: string;
+    job_id: string;
+    /** = launchpads.owner_wallet */
+    payer_wallet: string;
+    kind: PaymentKind;
+    usd_amount: DbNumeric;
+    lamports: DbBigint;
+    quote_expires_at: Timestamptz;
+    tx_signature: string | null;
+    status: PaymentStatus;
+    refund_signature: string | null;
+    created_at: Timestamptz | null;
+}
+export interface ConversationRow {
+    id: string;
+    owner_wallet: string;
+    /** Null while designing, set when the spec is confirmed. */
+    launchpad_id: string | null;
+    created_at: Timestamptz | null;
+}
+export interface ChatMessageRow {
+    id: number;
+    conversation_id: string;
+    role: ChatRole;
+    content: string;
+    created_at: Timestamptz | null;
+}
+export interface JobEventRow {
+    id: number;
+    job_id: string;
+    /** Shown in the chat in real time. */
+    message: string;
+    created_at: Timestamptz | null;
+}
+export interface FlagRow {
+    key: FlagKey;
+    value: boolean;
+}
+/** Table name -> row type. */
+export interface Tables {
+    users: UserRow;
+    launchpads: LaunchpadRow;
+    jobs: JobRow;
+    payments: PaymentRow;
+    conversations: ConversationRow;
+    chat_messages: ChatMessageRow;
+    job_events: JobEventRow;
+    flags: FlagRow;
+}
+export type TableName = keyof Tables;

package/dist/db.js

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { SolanaAddress } from './spec.js';
+/**
+ * Row types of the Supabase tables (docs/INTERFACES.md §5). Column names are kept in snake_case.
+ * Nullability mirrors the SQL exactly: a column without `not null` is typed `| null`, even when
+ * it has a default.
+ */
+export const LaunchpadStatus = z.enum(['draft', 'live', 'sleeping', 'disabled']);
+/** One DNS label: lowercase letters, digits and inner dashes, 1 to 63 characters. */
+const HOST_LABEL = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?';
+const HOST_NAME_RE = new RegExp(`^(?=.{4,253}$)(?:${HOST_LABEL}\\.)+[a-z]{2,63}$`);
+const VERCEL_APP_HOST_RE = new RegExp(`^${HOST_LABEL}\\.vercel\\.app$`);
+/**
+ * Shape of `launchpads.site_host` (migration 0011 holds the same CHECK): a lowercase DNS name
+ * without scheme, port, path or trailing dot. Under `vercel.app` (Vercel's production aliases),
+ * exactly one label; `vercel.app` itself is never a site host.
+ */
+export function isSiteHost(value) {
+    if (typeof value !== 'string' || value === 'vercel.app' || !HOST_NAME_RE.test(value)) {
+        return false;
+    }
+    return !value.endsWith('.vercel.app') || VERCEL_APP_HOST_RE.test(value);
+}
+/** A site host on `vercel.app` (`<one label>.vercel.app`). */
+export function isVercelAppHost(value) {
+    return isSiteHost(value) && value.endsWith('.vercel.app');
+}
+/**
+ * The recorded `site_host` of the launchpad `slug`, when a reader may trust it (relay origins,
+ * upload `auth.host`, links to the site): exactly `<one label>.vercel.app` (an alias of the
+ * launchpad's own Vercel project, checked by the builder before it records one), or exactly
+ * `<slug>.<clientsDomain>`. Any other host, however well formed (another domain, the subdomain of
+ * another launchpad), is ignored: null. `clientsDomain` is lowercase (readClientsDomain).
+ */
+export function trustedSiteHost(siteHost, slug, clientsDomain) {
+    if (!isSiteHost(siteHost))
+        return null;
+    if (isVercelAppHost(siteHost))
+        return siteHost;
+    return clientsDomain !== null && siteHost === `${slug}.${clientsDomain}` ? siteHost : null;
+}
+export const SiteHost = z.string().refine(isSiteHost, {
+    error: 'Must be a lowercase host name (one label under vercel.app)',
+});
+export const PaymentStatus = z.enum(['quoted', 'confirmed', 'expired', 'refunded']);
+export const PaymentKind = z.enum(['creation', 'modification']);
+export const ChatRole = z.enum(['user', 'assistant', 'system']);
+/** Kill switches. */
+export const FlagKey = z.enum([
+    'deploys_paused',
+    'buyback_paused',
+    'signups_paused',
+    'claims_paused',
+    'cashbox_sweep_paused',
+    'refunds_paused',
+    'jupiter_claims_paused',
+]);
+/**
+ * `jobs.owner_tx_details` (jsonb): the public accounts of the launch transaction stored in
+ * `jobs.owner_tx`, as the signer reported them (`details` of `POST /v1/launch-coin/prepare`). The
+ * builder writes it in the same update as `owner_tx`; apps/web pins these accounts when it checks
+ * the stored transaction (`verifyLaunchCoinTransaction` of @forge/core) and hands them to the
+ * browser (`OwnerTransactionLaunch`), instead of reading them back from the transaction.
+ * `config` is the launchpad coin config. Null on rows written before migration 0009.
+ */
+export const JobOwnerTxDetails = z.object({
+    config: SolanaAddress,
+    pool: SolanaAddress,
+    /** FORGE creator wallet of the launchpad: pool creator and durable nonce authority. */
+    creator: SolanaAddress,
+    /** Durable nonce account of the launch transaction. */
+    nonceAccount: SolanaAddress,
+    /** Coin metadata URI written by the pool creation (https, kept exactly as sent). */
+    metadataUri: z.url({ protocol: /^https$/, error: 'Must be an https URL' }),
+});