@forgedevv/shared 0.0.0-stage → 0.1.0

package/dist/spec.d.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+/** Base58 Solana public key (32 to 44 characters). */
+export declare const SolanaAddress: z.ZodString;
+export type SolanaAddress = z.infer<typeof SolanaAddress>;
+/** Launchpad slug: becomes `<slug>.<clients-domain>`. */
+export declare const Slug: z.ZodString;
+/** Pure check of the pool creation fee bound: 0 (when allowed) or within [min, max] SOL. */
+export declare function isValidPoolCreationFeeSol(value: number): boolean;
+/**
+ * True when a SOL amount converts exactly to lamports: finite, with at most 9 decimals (the same
+ * rule as `solToLamports` in @forge/core, which refuses anything else at build time).
+ */
+export declare function hasAtMostSolDecimals(value: number): boolean;
+/**
+ * Launchpad specification produced by the design chat, consumed by the builder and the signer
+ * (docs/INTERFACES.md §2). Bounds come from CLIENT_BOUNDS.
+ */
+export declare const LaunchpadSpec: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    ownerWallet: z.ZodString;
+    name: z.ZodString;
+    slug: z.ZodString;
+    quote: z.ZodLiteral<"SOL">;
+    tradingFeeBps: z.ZodNumber;
+    coinCreatorSharePct: z.ZodDefault<z.ZodNumber>;
+    poolCreationFeeSol: z.ZodNumber;
+    antiSniper: z.ZodDefault<z.ZodBoolean>;
+    theme: z.ZodObject<{
+        primaryColor: z.ZodString;
+        accentColor: z.ZodString;
+        darkMode: z.ZodBoolean;
+        tagline: z.ZodString;
+        logoUrl: z.ZodOptional<z.ZodURL>;
+        designNotes: z.ZodString;
+    }, z.core.$strip>;
+    launchpadCoin: z.ZodObject<{
+        name: z.ZodString;
+        symbol: z.ZodString;
+        description: z.ZodString;
+        imageUrl: z.ZodURL;
+        firstBuySol: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Parsed spec (defaults applied). */
+export type LaunchpadSpec = z.infer<typeof LaunchpadSpec>;
+/** Spec before parsing (fields with defaults are optional). */
+export type LaunchpadSpecInput = z.input<typeof LaunchpadSpec>;
+type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/** Partial spec while the chat fills it (docs/frontend/CONTRACT.md). Complete = LaunchpadSpec. */
+export type LaunchpadSpecDraft = DeepPartial<Omit<LaunchpadSpecInput, 'version' | 'quote'>> & {
+    version?: 1;
+    quote?: 'SOL';
+};
+/** Draft validation result. `errors` keys are dotted field paths, e.g. "launchpadCoin.symbol". */
+export interface SpecValidation {
+    complete: boolean;
+    errors: Record<string, string>;
+}
+/**
+ * Validates a draft against LaunchpadSpec. `version` and `quote` are fixed by the contract and
+ * filled in when missing. Keeps the first error message per field path.
+ */
+export declare function validateSpecDraft(draft: LaunchpadSpecDraft): SpecValidation;
+export {};

package/dist/spec.js

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+import { CLIENT_BOUNDS } from './constants.js';
+/** Base58 Solana public key (32 to 44 characters). */
+export const SolanaAddress = z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/, {
+    error: 'Invalid Solana address',
+});
+const HexColor = z.string().regex(/^#[0-9a-fA-F]{6}$/, {
+    error: 'Color must be a 6-digit hex value like #7C3AED',
+});
+/** Only http(s) URLs are accepted for images and logos rendered on client sites. */
+const HttpUrl = z.url({ protocol: /^https?$/, error: 'Must be an http(s) URL' });
+/** Launchpad slug: becomes `<slug>.<clients-domain>`. */
+export const Slug = z.string().regex(/^(?=.{3,32}$)[a-z0-9](?:[a-z0-9]|-(?!-))*[a-z0-9]$/, {
+    error: 'Slug must be 3 to 32 characters: lowercase letters, digits and single dashes, not at the start or end',
+});
+/** Metaplex limits on-chain names to 32 UTF-8 bytes, not 32 characters. */
+function utf8Bytes(value) {
+    let bytes = 0;
+    for (const char of value) {
+        const code = char.codePointAt(0) ?? 0;
+        bytes += code < 0x80 ? 1 : code < 0x800 ? 2 : code < 0x10000 ? 3 : 4;
+    }
+    return bytes;
+}
+const { tradingFeeBps, coinCreatorSharePct, poolCreationFeeSol } = CLIENT_BOUNDS;
+/** Pure check of the pool creation fee bound: 0 (when allowed) or within [min, max] SOL. */
+export function isValidPoolCreationFeeSol(value) {
+    if (value === 0)
+        return poolCreationFeeSol.allowZero;
+    return value >= poolCreationFeeSol.min && value <= poolCreationFeeSol.max;
+}
+/** Decimals of SOL: 1 SOL = 10^9 lamports. */
+const SOL_DECIMALS = 9;
+/**
+ * True when a SOL amount converts exactly to lamports: finite, with at most 9 decimals (the same
+ * rule as `solToLamports` in @forge/core, which refuses anything else at build time).
+ */
+export function hasAtMostSolDecimals(value) {
+    if (!Number.isFinite(value))
+        return false;
+    return Number(value.toFixed(SOL_DECIMALS)) === value;
+}
+const SOL_DECIMALS_ERROR = `must have at most ${SOL_DECIMALS} decimals (1 lamport)`;
+/**
+ * Launchpad specification produced by the design chat, consumed by the builder and the signer
+ * (docs/INTERFACES.md §2). Bounds come from CLIENT_BOUNDS.
+ */
+export const LaunchpadSpec = z.object({
+    version: z.literal(1),
+    /** Client wallet = session wallet = payer = feeClaimer of both configs. */
+    ownerWallet: SolanaAddress,
+    name: z.string().min(2).max(32),
+    slug: Slug,
+    quote: z.literal('SOL'),
+    tradingFeeBps: z.number().int().min(tradingFeeBps.min).max(tradingFeeBps.max),
+    coinCreatorSharePct: z
+        .number()
+        .int()
+        .min(coinCreatorSharePct.min)
+        .max(coinCreatorSharePct.max)
+        .default(coinCreatorSharePct.default),
+    poolCreationFeeSol: z
+        .number()
+        .refine(isValidPoolCreationFeeSol, {
+        error: `poolCreationFeeSol must be 0 or between ${poolCreationFeeSol.min} and ${poolCreationFeeSol.max} SOL`,
+    })
+        .refine(hasAtMostSolDecimals, { error: `poolCreationFeeSol ${SOL_DECIMALS_ERROR}` }),
+    antiSniper: z.boolean().default(true),
+    theme: z.object({
+        primaryColor: HexColor,
+        accentColor: HexColor,
+        darkMode: z.boolean(),
+        tagline: z.string().max(120),
+        logoUrl: HttpUrl.optional(),
+        /** Free-form instructions for the builder agent. */
+        designNotes: z.string().max(2000),
+    }),
+    launchpadCoin: z.object({
+        /**
+         * Written on-chain as is: no surrounding spaces (the on-chain launch refuses them), at most
+         * 32 UTF-8 bytes. Name, symbol and the metadata URI also share one byte budget in the launch
+         * transaction (`LAUNCH_METADATA_BUDGET_BYTES` in @forge/core).
+         */
+        name: z
+            .string()
+            .min(1)
+            .refine((value) => value.trim() === value, {
+            error: 'Coin name must not start or end with spaces',
+        })
+            .refine((value) => utf8Bytes(value) <= 32, { error: 'Coin name must be at most 32 bytes' }),
+        /** Written on-chain as is: the pattern leaves no room for spaces. */
+        symbol: z.string().regex(/^[A-Z0-9]{2,10}$/, {
+            error: 'Symbol must be 2 to 10 uppercase letters or digits',
+        }),
+        description: z.string().max(500),
+        imageUrl: HttpUrl,
+        /** Paid by the client. */
+        // The 10 SOL migration threshold means a first buy above ~10 SOL cannot fit in the curve.
+        firstBuySol: z
+            .number()
+            .min(0)
+            .max(10)
+            .refine(hasAtMostSolDecimals, { error: `firstBuySol ${SOL_DECIMALS_ERROR}` }),
+    }),
+});
+/**
+ * Validates a draft against LaunchpadSpec. `version` and `quote` are fixed by the contract and
+ * filled in when missing. Keeps the first error message per field path.
+ */
+export function validateSpecDraft(draft) {
+    const result = LaunchpadSpec.safeParse({ ...draft, version: 1, quote: 'SOL' });
+    if (result.success)
+        return { complete: true, errors: {} };
+    const errors = {};
+    for (const issue of result.error.issues) {
+        const key = issue.path.map(String).join('.');
+        if (!(key in errors))
+            errors[key] = issue.message;
+    }
+    return { complete: false, errors };
+}

package/dist/web-client.d.ts

@@ -0,0 +1,176 @@
+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;
+    siteUrl: string | null;
+    status: LaunchpadStatus;
+    coin: {
+        name: string;
+        symbol: string;
+        mint: string | null;
+        imageUrl: string;
+    };
+    coinsCount: number;
+    claimablePartnerFeesLamports: Lamports;
+    includedModificationsLeft: number;
+    activeJobId: string | null;
+}
+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>;
+    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,37 @@
+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.1.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.