@forgedevv/shared 0.0.0-stage → 0.2.0

package/dist/web-client.d.ts

@@ -0,0 +1,210 @@
+import type { GatingResponse, Lamports, OwnerTransactionSummary, Quote, Session } from './api.js';
+import type { LaunchpadStatus, PaymentKind } from './db.js';
+import type { FailedStage, JobStatus, JobType } from './jobs.js';
+import type { LaunchpadSpec, LaunchpadSpecDraft, SpecValidation } from './spec.js';
+/** `enabled: false` before the $FORGE launch (then `ok: true`). Amounts are raw token units. */
+export type Gating = GatingResponse;
+export interface Flags {
+    signupsPaused: boolean;
+}
+export interface Job {
+    id: string;
+    launchpadId: string;
+    type: JobType;
+    status: JobStatus;
+    attempts: number;
+    failedStage: FailedStage | null;
+    error: string | null;
+    previewUrl: string | null;
+    createdAt: string;
+    updatedAt: string;
+    refund?: {
+        lamports: Lamports;
+        signature: string;
+    } | null;
+}
+export interface JobEvent {
+    id: number;
+    jobId: string;
+    message: string;
+    createdAt: string;
+}
+export interface LaunchpadSummary {
+    id: string;
+    name: string;
+    slug: string;
+    /**
+     * Where the live site is: `https://<site_host>` when the builder recorded its exact host
+     * (`launchpads.site_host`), else `https://<slug>.<CLIENTS_DOMAIN>`. Null unless the launchpad is
+     * live or sleeping (or when neither is known).
+     */
+    siteUrl: string | null;
+    status: LaunchpadStatus;
+    coin: {
+        name: string;
+        symbol: string;
+        mint: string | null;
+        imageUrl: string;
+    };
+    coinsCount: number;
+    claimablePartnerFeesLamports: Lamports;
+    includedModificationsLeft: number;
+    activeJobId: string | null;
+    /** Status of `activeJobId` (null without one). Absent from older servers. */
+    activeJobStatus?: JobStatus | null;
+    /**
+     * A draft whose creation was refunded, with nothing in progress: `retryLaunchpad` can start it
+     * again with the same blueprint. The server re-checks everything (payments, refunds, kill
+     * switches, access) when asked. Absent from older servers: then treated as false.
+     */
+    canStartAgain?: boolean;
+    /**
+     * A draft whose creation jobs were all refunded but that cannot be started again yet, and why
+     * (null otherwise, and whenever a job is open: its tracker explains). The same rules as the
+     * route, so "start again" is never offered and then refused. Absent from older servers.
+     */
+    startAgainBlocked?: StartAgainBlockedReason | null;
+}
+/**
+ * Why "start again" is not available for a refunded draft:
+ * - `refund_pending`: money of an earlier attempt is still owed back (refund not recorded, or a
+ *   payment anomaly waiting for its manual refund);
+ * - `payment_pending`: a payment for an earlier attempt may still land or be confirmed;
+ * - `needs_support`: the team has to look at it first (on-chain setup recorded, or the limit of
+ *   refunded creations reached);
+ * - `invalid_spec`: the stored blueprint no longer passes the checks (design it again).
+ */
+export declare const START_AGAIN_BLOCKED_REASONS: readonly ["refund_pending", "payment_pending", "needs_support", "invalid_spec"];
+export type StartAgainBlockedReason = (typeof START_AGAIN_BLOCKED_REASONS)[number];
+export interface LaunchpadDetail extends LaunchpadSummary {
+    /** Complete spec. */
+    spec: LaunchpadSpecDraft;
+    onchain: {
+        launchpadConfig: string | null;
+        launchpadCoinConfig: string | null;
+        launchpadCoinMint: string | null;
+    };
+    versions: {
+        jobId: string;
+        createdAt: string;
+        request: string | null;
+        previewUrl: string | null;
+    }[];
+    jobs: Job[];
+}
+export type TxPhase = 'idle' | 'awaiting_signature' | 'sending' | 'confirmed' | 'rejected' | 'error';
+export interface TxResult {
+    phase: TxPhase;
+    signature?: string;
+    error?: string;
+}
+export declare const CLIENT_ERROR_CODES: readonly ["RATE_LIMITED", "UNAUTHORIZED", "GATING_REQUIRED", "SIGNUPS_PAUSED", "QUOTE_EXPIRED", "WRONG_WALLET", "BETA_NOT_INVITED", "NETWORK"];
+export type ClientErrorCode = (typeof CLIENT_ERROR_CODES)[number];
+/** Rejection of client functions; `message` is readable by the end user. */
+export declare class ClientError extends Error {
+    readonly code: ClientErrorCode;
+    constructor(code: ClientErrorCode, message: string);
+}
+export declare function isClientError(value: unknown): value is ClientError;
+export interface UseSessionResult {
+    session: Session | null;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    status: 'idle' | 'signing' | 'error';
+}
+export interface UseGatingResult {
+    gating: Gating | null;
+    loading: boolean;
+    recheck(): Promise<void>;
+}
+export interface UiChatMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+export interface UseChatOptions {
+    conversationId?: string;
+    launchpadId?: string;
+}
+export interface UseChatResult {
+    messages: UiChatMessage[];
+    send(text: string): void;
+    streaming: boolean;
+    spec: LaunchpadSpecDraft;
+    validation: SpecValidation;
+    rateLimited: boolean;
+    conversationId: string | null;
+}
+export interface UseJobResult {
+    job: Job | null;
+    events: JobEvent[];
+    loading: boolean;
+}
+export interface UseLaunchpadsResult {
+    launchpads: LaunchpadSummary[];
+    loading: boolean;
+    refresh(): void;
+}
+export interface UseLaunchpadResult {
+    launchpad: LaunchpadDetail | null;
+    loading: boolean;
+}
+/** Options of `formatSol` (not detailed in CONTRACT.md). */
+export interface FormatSolOptions {
+    /** Maximum number of fraction digits. */
+    maxFractionDigits?: number;
+    /** Append the " SOL" unit. */
+    withUnit?: boolean;
+}
+export type OnTxPhase = (phase: TxPhase) => void;
+/** One `data:` line of the `POST /api/chat` event stream (INTERFACES §6). */
+export type ChatStreamEvent = {
+    type: 'conversation';
+    conversationId: string;
+} | {
+    type: 'text';
+    delta: string;
+} | {
+    type: 'spec';
+    spec: LaunchpadSpecDraft;
+    validation: SpecValidation;
+} | {
+    type: 'error';
+    code: ClientErrorCode;
+    message: string;
+} | {
+    type: 'done';
+};
+/** Every function and hook exported by `apps/web/src/client/` (and by its mocks). */
+export interface WebClient {
+    useSession(): UseSessionResult;
+    useFlags(): Flags;
+    useGating(): UseGatingResult;
+    useChat(opts: UseChatOptions): UseChatResult;
+    confirmSpec(conversationId: string, spec: LaunchpadSpec): Promise<{
+        launchpadId: string;
+        jobId: string;
+    }>;
+    requestModification(launchpadId: string, conversationId: string, request: string): Promise<{
+        jobId: string;
+    }>;
+    getQuote(jobId: string, kind: PaymentKind): Promise<Quote>;
+    payQuote(quote: Quote, onPhase: OnTxPhase): Promise<TxResult>;
+    useJob(jobId: string): UseJobResult;
+    approvePreview(jobId: string): Promise<void>;
+    getOwnerTransactionSummary(jobId: string): Promise<OwnerTransactionSummary>;
+    signOwnerTransaction(jobId: string, onPhase: OnTxPhase): Promise<TxResult>;
+    useLaunchpads(): UseLaunchpadsResult;
+    useLaunchpad(id: string): UseLaunchpadResult;
+    claimPartnerFees(launchpadId: string, onPhase: OnTxPhase): Promise<TxResult>;
+    reactivateLaunchpad(launchpadId: string): Promise<void>;
+    /** "Start again" on a refunded draft: the new (or still unpaid) creation job, to pay next. */
+    retryLaunchpad(launchpadId: string): Promise<{
+        jobId: string;
+    }>;
+    formatSol(lamports: Lamports, opts?: FormatSolOptions): string;
+    formatUsd(n: number): string;
+    shortAddress(a: string): string;
+    explorerTxUrl(sig: string): string;
+}
+/** Client-facing labels of job statuses. For `failed`, show details according to `failedStage`. */
+export declare const JOB_STATUS_LABELS: Record<JobStatus, string>;

package/dist/web-client.js

@@ -0,0 +1,52 @@
+/**
+ * Why "start again" is not available for a refunded draft:
+ * - `refund_pending`: money of an earlier attempt is still owed back (refund not recorded, or a
+ *   payment anomaly waiting for its manual refund);
+ * - `payment_pending`: a payment for an earlier attempt may still land or be confirmed;
+ * - `needs_support`: the team has to look at it first (on-chain setup recorded, or the limit of
+ *   refunded creations reached);
+ * - `invalid_spec`: the stored blueprint no longer passes the checks (design it again).
+ */
+export const START_AGAIN_BLOCKED_REASONS = [
+    'refund_pending',
+    'payment_pending',
+    'needs_support',
+    'invalid_spec',
+];
+export const CLIENT_ERROR_CODES = [
+    'RATE_LIMITED',
+    'UNAUTHORIZED',
+    'GATING_REQUIRED',
+    'SIGNUPS_PAUSED',
+    'QUOTE_EXPIRED',
+    'WRONG_WALLET',
+    'BETA_NOT_INVITED',
+    'NETWORK',
+];
+/** Rejection of client functions; `message` is readable by the end user. */
+export class ClientError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ClientError';
+        this.code = code;
+    }
+}
+export function isClientError(value) {
+    return value instanceof ClientError;
+}
+/** Client-facing labels of job statuses. For `failed`, show details according to `failedStage`. */
+export const JOB_STATUS_LABELS = {
+    spec_ready: 'Awaiting payment',
+    paid: 'Payment received',
+    building: 'Building',
+    preview_ready: 'Preview ready',
+    approved: 'Approved',
+    onchain_setup: 'Connecting to Meteora',
+    awaiting_owner_signature: 'Your turn to sign the launch',
+    owner_signed: 'Launch signed',
+    deploying: 'Going live',
+    live: 'Live',
+    failed: 'Problem',
+    refunded: 'Refunded',
+};

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@forgedevv/shared",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Shared contracts (constants, zod schemas, types) between all FORGE apps. Published on npm as @forgedevv/shared.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Forgedevv/Forge.git",
+    "directory": "packages/shared"
+  },
+  "homepage": "https://github.com/Forgedevv/Forge/tree/main/packages/shared#readme",
+  "bugs": {
+    "url": "https://github.com/Forgedevv/Forge/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/**/*.test.*"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "zod": "4.6.5"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.