@forgedevv/shared 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog — @forge/shared
+
+All notable changes to `@forge/shared`, published on npm as `@forgedevv/shared` together with
+`@forgedevv/core` (same version). Versions follow semantic versioning. Changes before 0.3.0 are
+listed in the `@forge/core` changelog.
+
+## 0.3.0 — 2026-10-17
+
+### Changed (Jupiter fixes)
+
+- `FEES.jupiterIntegratorFeeBps` is 50 bps, was 30. It is the Jupiter Plugin `referralFee` after
+  graduation; Jupiter Ultra refuses any value outside 50..255 bps (checked by `@forge/core`
+  `assertJupiterReferralFeeBps`), and keeps 20% of it. `FEES.platformFeeBps` (30 bps, FORGE's own
+  buy button) is unchanged.

package/dist/api.d.ts

@@ -97,6 +97,10 @@ export declare const WEB_API_ROUTES: {
         readonly method: "POST";
         readonly path: "/api/launchpads/:id/reactivate";
     };
+    readonly launchpadRetry: {
+        readonly method: "POST";
+        readonly path: "/api/launchpads/:id/retry";
+    };
     readonly rpc: {
         readonly method: "POST";
         readonly path: "/api/rpc";
@@ -145,6 +149,7 @@ export declare const GatingResponse: z.ZodObject<{
     required: z.ZodString;
     balance: z.ZodString;
     enabled: z.ZodBoolean;
+    decimals: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type GatingResponse = z.infer<typeof GatingResponse>;
 export declare const FlagsResponse: z.ZodObject<{
@@ -206,6 +211,10 @@ export declare const LaunchpadModificationResponse: z.ZodObject<{
     jobId: z.ZodUUID;
 }, z.core.$strip>;
 export type LaunchpadModificationResponse = z.infer<typeof LaunchpadModificationResponse>;
+export declare const LaunchpadRetryResponse: z.ZodObject<{
+    jobId: z.ZodUUID;
+}, z.core.$strip>;
+export type LaunchpadRetryResponse = z.infer<typeof LaunchpadRetryResponse>;
 export declare const PaymentsQuoteRequest: z.ZodObject<{
     jobId: z.ZodUUID;
     kind: z.ZodEnum<{
@@ -368,17 +377,43 @@ export declare const RpcResponse: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type RpcResponse = z.infer<typeof RpcResponse>;
-/** Hex HMAC-SHA256 computed with SIGNER_HMAC_SECRET over `signerSignedPayload(...)`. */
+/** Lowercase hex HMAC-SHA256 computed with SIGNER_HMAC_SECRET over `signerSignedPayload(...)`. */
 export declare const SIGNER_SIGNATURE_HEADER = "X-Forge-Signature";
 /** Unix time in seconds, as a decimal string. */
 export declare 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 declare const SIGNER_NONCE_HEADER = "X-Forge-Nonce";
 /** Requests whose timestamp differs from the signer clock by more than this are rejected. */
 export declare const SIGNER_MAX_CLOCK_SKEW_SECONDS = 60;
+/** First line of the signed string. Any change to its layout gets a new tag. */
+export declare const SIGNER_SIGNATURE_VERSION = "forge-signer-v2";
+/** The request fields covered by the signer HMAC. */
+export interface SignerSignedFields {
+    /** HTTP method, uppercase (`POST`). */
+    method: string;
+    /** Request target exactly as sent: the path plus the query string (`/v1/configs?a=1`). */
+    path: string;
+    /** Same value as the timestamp header. */
+    timestamp: string;
+    /** Same value as the nonce header. */
+    nonce: string;
+    /** Lowercase hex SHA-256 of the raw body bytes (an empty body hashes zero bytes). */
+    bodySha256: string;
+}
 /**
- * Exact string fed to HMAC-SHA256: `<timestamp>.<raw body>`. The timestamp is covered by the MAC
- * so that a captured request cannot be replayed with a fresh timestamp.
+ * 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 declare function signerSignedPayload(timestamp: string, rawBody: string): string;
+export declare function signerSignedPayload(fields: SignerSignedFields): string;
 export declare const SIGNER_ROUTES: {
     readonly configs: {
         readonly method: "POST";

package/dist/api.js

@@ -51,6 +51,7 @@ export const WEB_API_ROUTES = {
     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
@@ -90,6 +91,8 @@ export const GatingResponse = z.object({
     /** 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() });
@@ -112,6 +115,12 @@ export const LaunchpadModificationRequest = z.strictObject({
     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). */
@@ -219,18 +228,52 @@ export const RpcResponse = z.object({
 // ---------------------------------------------------------------------------
 // Internal builder -> signer API (§7)
 // ---------------------------------------------------------------------------
-/** Hex HMAC-SHA256 computed with SIGNER_HMAC_SECRET over `signerSignedPayload(...)`. */
+/** 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: `<timestamp>.<raw body>`. The timestamp is covered by the MAC
- * so that a captured request cannot be replayed with a fresh timestamp.
+ * 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(timestamp, rawBody) {
-    return `${timestamp}.${rawBody}`;
+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' },

package/dist/constants.d.ts

@@ -12,8 +12,11 @@ export declare const PRICING: {
 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;
+    /**
+     * Jupiter Plugin referral fee (`referralFee`), after graduation only; Jupiter keeps 20 % of it.
+     * Jupiter Ultra accepts 50 to 255 bps (checked by @forge/core `assertJupiterReferralFeeBps`).
+     */
+    readonly jupiterIntegratorFeeBps: 50;
     /** FORGE creator share on the coin of every launchpad. */
     readonly forgeCreatorSharePct: 25;
 };

package/dist/constants.js

@@ -12,8 +12,11 @@ export const PRICING = {
 export const FEES = {
     /** Our fee on our own buy button (before graduation). */
     platformFeeBps: 30,
-    /** After graduation; Jupiter keeps 20 % of it. */
-    jupiterIntegratorFeeBps: 30,
+    /**
+     * Jupiter Plugin referral fee (`referralFee`), after graduation only; Jupiter keeps 20 % of it.
+     * Jupiter Ultra accepts 50 to 255 bps (checked by @forge/core `assertJupiterReferralFeeBps`).
+     */
+    jupiterIntegratorFeeBps: 50,
     /** FORGE creator share on the coin of every launchpad. */
     forgeCreatorSharePct: 25,
 };

package/dist/db.d.ts

@@ -13,6 +13,23 @@ export declare const LaunchpadStatus: z.ZodEnum<{
     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";
@@ -39,6 +56,9 @@ export declare const FlagKey: z.ZodEnum<{
     claims_paused: "claims_paused";
     cashbox_sweep_paused: "cashbox_sweep_paused";
     refunds_paused: "refunds_paused";
+    jupiter_claims_paused: "jupiter_claims_paused";
+    convert_paused: "convert_paused";
+    revenue_paused: "revenue_paused";
 }>;
 export type FlagKey = z.infer<typeof FlagKey>;
 /** ISO 8601 timestamp as returned by PostgREST for `timestamptz`. */
@@ -70,6 +90,13 @@ export interface LaunchpadRow {
     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

package/dist/db.js

@@ -6,6 +6,42 @@ import { SolanaAddress } from './spec.js';
  * 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']);
@@ -17,6 +53,9 @@ export const FlagKey = z.enum([
     'claims_paused',
     'cashbox_sweep_paused',
     'refunds_paused',
+    'jupiter_claims_paused',
+    'convert_paused',
+    'revenue_paused',
 ]);
 /**
  * `jobs.owner_tx_details` (jsonb): the public accounts of the launch transaction stored in

package/dist/web-client.d.ts

@@ -33,6 +33,11 @@ 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: {
@@ -45,7 +50,32 @@ export interface LaunchpadSummary {
     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;
@@ -167,6 +197,10 @@ export interface WebClient {
     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;

package/dist/web-client.js

@@ -1,3 +1,18 @@
+/**
+ * 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',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgedevv/shared",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Shared contracts (constants, zod schemas, types) between all FORGE apps. Published on npm as @forgedevv/shared.",
   "license": "UNLICENSED",
   "repository": {
@@ -29,7 +29,8 @@
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
-    "!dist/**/*.test.*"
+    "!dist/**/*.test.*",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public",