@gala-chain/launchpad-sdk 9.0.0-rc.0 → 9.0.0-rc.2

package/CHANGELOG.md

@@ -1,6 +1,27 @@
 # Changelog
 
-## 9.0.0-rc.0
+## 9.0.0-rc.2
+
+Since 9.0.0-rc.1 (published). Matches launchpad-backend-service-v3 MR !50 (merge and deploy it before
+the new filters work live).
+
+- **Token names on DTO routes are 1-25 letters and digits** (the backend raised `@TokenNameField()` from
+  20 to 25): `TOKEN_NAME_DTO_CONSTRAINT` (`MAX_LENGTH` 25, pattern `{1,25}`, description
+  `1-25 letters and digits`) and `dtoTokenNameSchema` (`.max(25, 'Token name must be at most 25
+  characters')`). A 21-25 character name is sent now; 26 is a `ValidationError`.
+- **`fetchPools` / `fetchAllPools` take `isGraduated` and `creatorAddress`.** `isGraduated` is a boolean
+  and BOTH values are sent (`"true"` / `"false"`: unlike `hasUpcomingShows` / `hasRecordings`, the
+  backend reads this one strictly); leave it out for no filter. `creatorAddress` is `eth|<40 hex>` or
+  `client|<24 hex>` (a `0x`-prefixed or bare 40-hex address is sent as `eth|...`); an empty string, an
+  array or any other text is a `ValidationError` and is never sent.
+
+## 9.0.0-rc.1
+
+Since 9.0.0-rc.0 (published): the sections "App-owned session" through "The stream socket" below
+(the app-session, browser-wallet, bundle-confirmation, error-answer, path-parameter, `PageInfo`,
+`fetchPools`, admin/overseer, trades/tokens/users/streaming and stream-socket contracts) and the
+later entries of "BREAKING CHANGES" and "Fixes" are new in rc.1; everything else in this section is
+rc.0's. Core peer floor is `>=1.0.0-rc.6 <2`.
 
 launchpad-sdk is launchpad-only. Everything that speaks to the GalaChain gateway generically is
 `@gala-chain/gala-core-sdk`'s (a peer dependency: install it beside launchpad-sdk); everything that
@@ -51,15 +72,23 @@ built declarations of both versions (`pnpm docs:migration`).
   schemas are zod 4, and it is no longer also a dependency) and the shared libraries. No longer
   dependencies: `@solana/web3.js`, `@solana/spl-token`, `dotenv`, `@modelcontextprotocol/sdk` (and,
   since the bridge move, `bs58` and `json-stringify-deterministic`).
-- **The bridge loads Solana only when used.** The bridge, balance-on-chain, token-list and wrap methods
-  load `@gala-chain/gala-core-sdk/bridge` (the one core entry that loads `ethers`,
-  `@solana/web3.js` and `@solana/spl-token`, core's optional peers) with `import()` at their first
-  call: an app that never bridges never loads Solana and need not install it; an app that bridges
-  installs those peers (a missing one is a `ConfigurationError` naming them). The CommonJS bundles
-  `require` it and the UMD bundle requires it or takes the `GalaCoreSDKBridge` global, so there is
-  one core copy in every build. A bridge or wrap call made with one wallet is refused
-  (`ConfigurationError`, nothing sent) if `setWallet` / `setWalletProvider` runs while `/bridge`
-  loads, rather than running as the next wallet. `getSupportedBridgeTokens()` is `async`.
+- **Bridging is explicit: the `bridge` loader.** The bridge, balance-on-chain, token-list and wrap
+  methods run on `@gala-chain/gala-core-sdk/bridge` (the one core entry that loads `ethers`,
+  `@solana/web3.js` and `@solana/spl-token`, core's optional peers), which the app hands over:
+  `new LaunchpadSDK({ ..., bridge: () => import('@gala-chain/gala-core-sdk/bridge') })` (type
+  `CoreBridgeLoader`; a page without a bundler passes a function resolving to the module it loaded
+  itself). The UMD bundle no longer looks for a `GalaCoreSDKBridge` global. launchpad-sdk
+  names neither that module nor Solana in any built bundle: a bundler (Vite, webpack, Metro)
+  resolves every load it sees, a lazy `import()` included, so the earlier `import()` inside the SDK
+  made every app's build need Solana (an app's Vite build failed with 13 `MISSING_EXPORT` errors on
+  `@solana/web3.js` / `@solana/spl-token`). Without the loader a bridge or wrap call is a
+  `ConfigurationError` (`field: 'bridge'`) naming it; with it, the module is loaded once per SDK at
+  the first such call, and a failed load (the peers are not installed) is a `ConfigurationError`
+  naming them, tried again at the next call. `check:pack` scans every built bundle of the packed
+  package for a `@gala-chain/gala-core-sdk/bridge` or `@solana/*` load (`scripts/runtime-specifiers.ts`).
+  A bridge or wrap call made with one wallet is refused (`ConfigurationError`, nothing sent) if
+  `setWallet` / `setWalletProvider` runs while `/bridge` loads, rather than running as the next
+  wallet. `getSupportedBridgeTokens()` is `async`.
 - **The public surface re-exports nothing** (`tests/public-surface.test.ts` pins both entries' export
   lists and fails on any export declared outside `src/`). Removed from the main and `/native`
   entries: `generateEIP712Types` and `GalaChainSigner` (core's), the duplicate EIP-712 types
@@ -68,8 +97,469 @@ built declarations of both versions (`pnpm docs:migration`).
   (core's), `generateUniqueKey` (core's `createUniqueKey`), and the demo `.env` loaders `getEnv`,
   `getEnvOrThrow`, `loadEnvWithFallback`.
 
+### App-owned session (a browser app's httpOnly-cookie JWT session)
+
+- **`session` in `LaunchpadSDKConfig`.** A browser app (launchpad-frontend-v3) keeps its own JWT
+  session: the refresh token is an httpOnly cookie the backend sets for `cookieSession: true`
+  logins, and the app is the one token authority. With `session: { accessToken, onUnauthorized,
+  credentials? }` every launchpad-backend request takes its bearer from `accessToken()` (awaited per
+  request), a 401 goes to `onUnauthorized(rejectedToken)` and is retried once with the token it
+  returns (`null`: the 401 stands), the launchpad-backend client sends credentials (unless
+  `credentials: 'omit'`), and the SDK stores no token (services that attach "the JWT" attach
+  nothing; the client adds the session's bearer). No other host (gateway, bundler, dex-api, swap
+  backend) ever sees the session or credentials. Exclusive with `accessToken`. Pair it with
+  `signer` + `walletAddress`: `wallet` / `walletProvider` sign every launchpad request (`Sign`).
+- **`loginWithSignature({ address, message, signature, publicKey? })`**: `POST /auth/login` with a
+  signature the caller made (a browser wallet signs `Sign in to Launchpad t:<ms>` itself); with a
+  session it asks for the cookie session and stores nothing. **`loginWithDevBypass(address)`**: the
+  backend's non-production signature bypass.
+- With a session, `refreshToken()` is `POST /auth/refresh` with `{}`, no bearer and the cookie;
+  `logout({ allDevices, accessToken })` always revokes on the server (bearer as handed over, never
+  refreshed); `ensureValidToken()` is the session's current token. Auth-endpoint failures are an
+  `AuthError` with the backend's `statusCode` (401/403: the session was rejected; 429/5xx/none:
+  transient). `tests/app-session.test.ts` drives each through a real axios instance.
+
+### Browser-app wallet signing
+
+- **`BrowserWalletSigner.fromEip1193(provider, keyAddress, options?)`**: a browser app holds the
+  wallet's raw EIP-1193 provider, not an ethers one. The factory builds the ethers `BrowserProvider`
+  the typed-data path reads the network and the selected account from, keeps the raw `request` for
+  `signObject`, and takes the key as `0x` or `eth|` (a `client|` alias is refused: it names no key).
+  The bytes are those of the constructor path (bundler-typed-data and wallet-providers goldens
+  unchanged; `tests/wallet-signers-app.test.ts` compares both paths over a real `BrowserProvider`).
+- **`WALLET_ACCOUNT_CHANGED`** (`LaunchpadSDKError`, `details.walletAccount` / `signerAccount`):
+  `BrowserWalletSigner` refuses to sign when the wallet's selected account is not its key. Same
+  message as before; it was a plain `Error`, which the bundler transport rewrapped as
+  `LAUNCHPAD_SIGNING_FAILED`.
+- **`WALLET_USER_REJECTED`**: the bundler transport tells a decline in the wallet (gala-core-sdk's
+  `isWalletUserRejection`: `4001`, `ACTION_REJECTED`, Gala Wallet's decline, core's
+  `SIGNING_FAILED`/`user_rejected`) apart from other signing failures, with the wallet's code in
+  `details.walletCode`. Other failures stay `LAUNCHPAD_SIGNING_FAILED`; an SDK error passes through.
+- **Gala Wallet typed data selects the account.** `GalaWalletSigner.signTypedData` switches the
+  extension (`setAddress`, where it offers it) to `selectAddress`, else the Ethereum account the
+  request names, inside gala-core-sdk's per-wallet select-then-sign queue
+  (`withGalaWalletIdentity`), and signs through the `wallet` option when one is given (it read
+  `window.gala` even then, while `signObject` used the option).
+- **`GalaWalletSigner` option `verifyActiveAccount` (default `false`)**: the app's check before a Gala
+  Wallet signature. On, the signer reads the wallet's active account (`wallet.address`, else
+  `eth_accounts` when the wallet has not reported one since the page loaded) and refuses with
+  `WALLET_ACCOUNT_CHANGED` (`details.walletAccount` null when none was reported) unless it is the
+  signer's key; the RPC order is that check, `setAddress`, `eth_signTypedData`. Off by default so the
+  six recorded `galaWalletEthAddress` vectors of `bundler-typed-data.golden.json` are unchanged (the
+  check adds an `eth_accounts` request); the opt-in sequences are pinned by the new
+  `tests/golden/gala-wallet-verify-account.golden.json`. A signer that names no Ethereum key
+  (`client|` alias without an Ethereum `selectAddress`) is refused at construction
+  (`INVALID_SIGNER_OPTIONS`). `BrowserWalletSigner` needs no option: it always compares the wallet's
+  selected account with its key.
+
+### Bundle confirmation for a browser app
+
+- **`bundleSocketFactory` in `LaunchpadSDKConfig`** (passed to `BundlerTransport`): the app's own
+  bundler socket, with its reconnect settings. Each `wait()` adds its listener for the bundle's
+  event on the socket the factory returns and removes it when the wait ends; that socket is never
+  disconnected (a socket the transport opens itself still is).
+- **`sdk.launchpad.attach({ bundleId, method, uniqueKey, tokenName? })`** (and
+  `BundlerTransport.attach`): a `BundleSubmission` for a bundle sent before a reload, whose `wait()`
+  confirms exactly as the original's (socket event raced against the REST confirmation, which also
+  answers for a bundle that settled while nobody listened). Nothing is signed or sent until
+  `wait()`. Refused with `INVALID_BUNDLE_ATTACHMENT` (`details.field`): empty `bundleId` /
+  `uniqueKey`, a method the bundler does not accept, a `CreateSale` without `tokenName`. New exports:
+  `LAUNCHPAD_WRITE_METHODS` (`LaunchpadWriteMethod` is now derived from it), types
+  `BundleAttachment`, `BundleSocket`, `SocketFactory`. `LaunchpadWriteTransport` gains `attach`.
+- The bundler (bundler-backend origin/main, `src/socket/socket.gateway.ts`) emits only
+  `{ status, data }` (lowercase; `PENDING` / `PROCESSED` / `FAILED`), never `{ Status, Data }`, so
+  `parseBundleResult` is unchanged.
+
+### The backend's error answer on `NetworkError`
+
+- **`serverMessage`, `serverError`, `details`, `body`** (type `NetworkErrorServerAnswer`) beside
+  `statusCode`. Before, an HTTP failure was `NetworkError("HTTP <M> <url>: Request failed with status
+  code N")` and the backend's body survived only on `originalError.launchpadError`. The launchpad
+  backend (origin/main `GlobalExceptionFilter`) answers `{ status, error: true, message }`
+  (HttpException: validation pipe, `sendResult`, guards) or `{ statusCode, message }` (CustomError,
+  413, unhandled 500): `serverMessage` is that `message` (an array is joined with `,`, as
+  `String(array)` shows it), `serverError` is a string `error` only (`true` is not one), `body` the
+  whole body (or the text of a non-JSON answer). Messages are unchanged.
+- **A wrapped NetworkError keeps them**: `new NetworkError(msg, status?, originalError?, answer?)`
+  takes the answer of `originalError` (an axios error's response, or another NetworkError) when
+  not given, and `handleNetworkError` (the `error-wrapper` `withErrorHandling` wrap services put
+  around the client's error) also takes the wrapped NetworkError's status: it was `undefined`
+  there. (A bare `createNetworkError(msg, undefined, inner)` does not take the status: the
+  gateway-reads golden pins `statusCode` absent on the GalaChain balance read's wrapped 400.)
+  `createNetworkError` takes the answer as an optional fourth argument;
+  `response-handlers.assertResponseSuccess` puts a 2xx error envelope's body on it.
+- Paths that turned the client's NetworkError into another error now keep it a NetworkError, same
+  message: `PoolService.fetchToken`'s 404 "Token not found: <name>" (was a plain `Error`),
+  `UserService.uploadProfileImage`'s "Profile image upload failed: ..." for an HTTP refusal (was a
+  `ValidationError` `UPLOAD_FAILED`; other failures still are), and `LaunchpadPriceService`'s spot
+  price failure now wraps the original.
+- The response interceptor's `launchpadError.error` is set only when the body's `error` is a string
+  (it cast the backend's `true` to a string).
+
+### Path parameters are spelled as the backend compares them
+
+- `buildEndpoint` (every `StreamTokenServiceBase` service) lowercased EVERY path value. It now
+  follows `PATH_PARAM_CASING`, decided per parameter from launchpad-backend origin/main's routes:
+  `tokenName` (the pool lookup's `normalizeTokenName`), `address` and `userAddress`
+  (`normalizeAddress`) stay lowercased; `assetId` and `targetId` (Mux ids, mixed-case, compared
+  exactly), `id` (numeric invite ids) and `code` (invite codes, matched exactly) are sent as given.
+  A parameter the table does not name is refused. Changed on the wire: `getRecordingDownload` /
+  `deleteRecording` (`/v1/tokens/:tokenName/recordings/:assetId[/download]`) and
+  `removeSimulcastTarget` (`/v1/tokens/:tokenName/simulcasts/:targetId`): a mixed-case Mux id was
+  lowercased into one the backend does not have; the moderator and overseer `getInviteByCode`
+  (`/v1/{moderator,overseer}-invites/code/:code`) send the code as given (generated codes are
+  lowercase hex, so only a code typed in another case differs); the invite `:id` routes are
+  unchanged in effect (digits).
+
+### `PageInfo` is the backend's `pageInfo`
+
+- **`PageInfo` = `{ hasNextPage, endCursor?, hasPreviousPage?, startCursor?, totalCount? }`**, the
+  backend's own keys (launchpad-backend origin/main `buildPageInfo`: `endCursor` / `startCursor`
+  are `string | null`). It declared `nextCursor` / `prevCursor` / `hasPrevPage`, while every list
+  but two passed the backend's `pageInfo` through unchanged (so at run time it was `endCursor`), and
+  `PoolService` / `UserService` renamed the backend's keys to the declared ones. Now no list renames:
+  pools and user token lists return the backend's `pageInfo` (`pageInfoOf`, which drops a field of
+  the wrong type), and the cursor walkers (`autoPaginateWithCursor`, `fetchAllPools`, the vault
+  token-name lookup) follow `endCursor` (`nextCursorOf`): `autoPaginateWithCursor` stopped after
+  the first page of every passed-through list. They also stop when the backend repeats the cursor
+  just used (`fetchAllPools` went back to page 1 on a missing cursor).
+- `totalCount` is set only on results the SDK assembles from every page (`fetchAll...`): the
+  backend sends no count. Removed with it: `UserTokenListResult.total` (always undefined), the
+  dead `InternalFetchUserBalancesResponse` type, and the top-level `count` / `total` / `nextCursor`
+  / `prevCursor` / `hasNextPage` / `hasPrevPage` fields of the internal pool and user-list response
+  types (the backend answers `{ tokens | token | launches, pageInfo }`). Migration: read
+  `pageInfo.endCursor` (`?? undefined` for a `cursor` option) where you read `nextCursor`.
+
+### `fetchPools` matches `GET /v1/tokens` (launchpad-backend origin/main `FetchPoolDto`)
+
+- **`type` and `streamStatus` in the backend's spelling, any case.** `type` RECENT / POPULAR /
+  RECORDINGS / SECONDS_STREAMED (`POOL_FETCH_TYPES`; the backend compares case-sensitively, so it is
+  sent uppercase), `streamStatus` IDLE / ACTIVE / DISABLED (`POOL_STREAM_STATUSES`). The lookup
+  tables were lowercase-keyed and DROPPED the app's `'POPULAR'` / `'ACTIVE'` without a word; lowercase
+  still works. A value the backend does not accept is a `ValidationError`, never dropped.
+- **`pageSize` 1 to 100** (`POOL_LIST_MAX_PAGE_SIZE`, the backend's `MediumListQueryDto` maximum):
+  it was silently clamped to 20. Larger, zero or fractional is a `ValidationError`. `fetchAllPools`
+  reads pages of 100 (was 20). Default still 10.
+- `recentlyStreamed` (integer 1 to 720), `language` (ISO 639-1) and `search` (at most 255) are
+  checked before sending, as the backend would refuse them.
+- **`hasUpcomingShows` / `hasRecordings`: only `true` is sent.** The backend's boolean conversion
+  (`@Type(() => Boolean)` with implicit conversion) reads `"false"` as true, so `false` used to turn
+  the filter ON; it now sends nothing (no filter).
+- `isGraduated` / `creatorAddress` are NOT added: origin/main's `FetchPoolDto` has neither and the
+  pipe forbids unknown properties (a 400).
+- One pool-list reader: the private `LaunchpadAPI.fetchPools` / `fetchPoolsFromAPI` copy (used to
+  find a vault's token name for a sell-fee quote) is removed; that lookup reads `PoolService`. The
+  copy read `hasNextPage` / `nextCursor` at the top of `data`, where the backend never puts them,
+  so it never got past page 1. `LaunchpadService` / `fetchAllPools` take `FetchPoolsOptions` (their
+  inline option types still named `offset` / `limit`). The zod `poolFetchTypeSchema` takes all four
+  types; the public `PoolFetchType` is the one type (`'RECENT' | 'POPULAR' | 'RECORDINGS' |
+  'SECONDS_STREAMED'`, it was the schema's two).
+
+### Admin and overseer contracts (launchpad-backend origin/main)
+
+- **`revokeOverseerInvite` and `revokeOverseer` sent no Authorization.** The auth headers were passed
+  in the query-params slot of `HttpClient.delete`: the request went out unauthenticated and the
+  header names became query parameters. They are headers now (`tests/g3-admin-wire.test.ts`).
+- **Restricted token names carry the session bearer.** `getRestrictedNames` / `updateRestrictedNames`
+  (Overseer-only routes) sent no Authorization. An empty `content` is accepted (the backend takes any
+  string; it clears the list); `UpdateRestrictedNamesResponse` is `{ content }` (the backend echoes the
+  stored content), it was typed `{ success: true }`.
+- **Invite codes are validated like the backend**: any non-empty string up to 64 characters
+  (`INVITE_CODE_CONSTRAINT.MAX_LENGTH`, was 100 for overseer codes and "64 hex" for moderator codes).
+  An unknown code is the backend's 404, which a claim page relies on to fall through from the overseer
+  lookup to the moderator one; it used to be a client-side `ValidationError`.
+- **`sdk.getHealth()`** (`GET /health`, public): `HealthCheckResponse` (`status` plus database, redis,
+  mux, rabbitmq, galachain_query, galachain_launchpad). A critical dependency down is HTTP 503 and
+  throws a `NetworkError`.
+- **`sdk.getEventStats()`, `sdk.queryEvents(options)`** (`GET /v1/events/stats`, `GET /v1/events`,
+  Admin API key or Overseer): the routes answer BARE bodies, which the service reads and shape-checks.
+  `queryEvents` pages by `page` / `limit` (1..100). `eventTypes` / `categories` are sent as a
+  REPEATED key (one value is sent twice): the backend validates them with `@IsArray` behind Express 5's
+  simple query parser, where a comma list or `key[]=` is refused.
+- **`getMessageStats` reads the bare object** `GET /v1/messages/stats` answers (it required a
+  `{ data }` envelope and could never succeed against the backend).
+
+- **The flag filters validate what `GetFlagsQueryDto` takes**: the token filter is 1-50 letters and digits
+  (a 1-character filter threw; see the token name rules below) and the addresses
+  (`reporterAddress`, `reportedUserAddress`, also `createFlag`'s) are the forms `@GalaChainAddressField()`
+  takes after its normalisation: `eth|<40 hex>`, `0x<40 hex>`, 40 hex, `client|<24 hex>` or 24 hex
+  (`isBackendUserAddress` / `assertBackendUserAddress`). A bare client id is accepted now; a partial
+  address and `client|<name>` stay refused, because the backend answers 400 for them.
+- **`updateModeratorInvite({ inviteId, description: '' })` is a valid update**: the backend's `UpdateModeratorInviteDto.description` has no minimum and its service updates on
+  `description !== undefined`, so `''` alone clears the label (the SDK refused it with "At least one of
+  role or description"). An update with neither field is still refused.
+
+### Trades, tokens, users and streaming contracts (launchpad-backend origin/main)
+
+- **`fetchTrades` reaches its route.** It sent the literal `/v1/tokens/:tokenName/trades` with the
+  name in a query parameter; the token is now in the path (lowercased, as the backend compares it).
+  `TradeQueryItem` types `tokenSymbol`, which `GET /v1/trades` returns. `getTrades` already unwrapped
+  the `{ data }` body (verified on the wire, `tests/g3-trades-wire.test.ts`).
+- **`fetchTokenStats` returns what the backend sends**: `{ holdersCount, chatMessageCount, commentCount,
+  roomCount }` (`TokenStatsData`, was `EngagementStatsData`). It required a `stats` wrapper the backend
+  has none of, and so could never succeed; `totalEngagement`, participants and activity fields were
+  never sent.
+- **`updateTokenConfig` takes `chatEnabled`** (was `messagesEnabled`, which the backend refuses with 400:
+  its `UpdateTokenConfigDto` has `chatEnabled`).
+- **`fetchLaunchpadFee()` returns the number** (`data.feeAmount`); it returned the `{ feeAmount }` object
+  typed as a number.
+- **Images reach their routes.** `uploadImageByTokenName` posts to `/v1/tokens/:tokenName/image` (the
+  placeholder went out literally, the name in a query parameter) and `uploadProfileImage` to
+  `POST /v1/users/me/image` (it used the token route); the profile upload needs no address or wallet.
+- **`updateProfile` sends what is given.** `address` is optional (validated, not sent), `fullName` and
+  `profileImage` are optional (at least one), `profileImage: ''` clears the image, and the profile is no
+  longer fetched first to send the old image back. `fullName` is validated like the backend's
+  `UpdateProfileDto` (a trimmed 2..20 letters, one optional second word) and no wallet is required, only
+  a JWT.
+- **User token lists take pages up to 100** (`USER_PAGINATION_CONSTRAINT.MAX_LIMIT` 20 -> 100; the
+  backend takes up to 1000, default 50); `getManagedTokens` sends no `pageSize` unless asked, so the
+  backend's 50 applies (the SDK's default 10 cut a longer list off).
+- **`fetchVolumeData` returns the chart**: `{ dataPoints, isPreviousData, nextTime? }` with the candles
+  typed as the backend sends them (`startTime`, `openPrice`, `highPrice`, `lowPrice`, `closePrice`,
+  `volume`); `dataPoints` held the whole `{ data, isPreviousData }` object typed as `{ timestamp, value }[]`.
+- **`getTradeQuote` takes an `AbortSignal`** (`TradeQuoteParams.signal`); `PlatformStatsData` volumes are
+  numbers (typed as strings); `listOverseerUsers` accepts `ASC` / `DESC` (the backend reads the order
+  case-insensitively).
+- **Recordings match `GET /v1/tokens/:tokenName/recordings`**: a bare array with no paging.
+  `getStreamRecordings({ tokenName })` returns `{ recordings, tokenName }` (the fabricated `page`, `limit`,
+  `total`, `hasNext` are gone; the old code read `data.recordings` and could never succeed). A recording is
+  `{ id, playbackId, status, duration, createdAt, masterAccess, aspectRatio?, assets? }` (was `assetId`,
+  `tokenName`, `downloadable`, `fileSize`, `thumbnailUrl`); `RECORDING_STATUS` is Mux's `preparing` /
+  `ready` / `errored`. An unknown token is a `NetworkError` with `statusCode` 404.
+- **Simulcasts match `/v1/tokens/:tokenName/simulcasts`**: the list is a bare array behind the owner's
+  session bearer (it was sent without Authorization); a target is `{ id, url, status, passthrough? }`;
+  `addSimulcastTarget` sends `{ platform, url, streamKey, passthrough? }` with the platform in lowercase
+  (`'youtube' | 'twitch' | 'facebook' | 'custom'`, `SIMULCAST_PLATFORM`), as the backend's
+  `CreateSimulcastTargetDto` requires (it refused `rtmpUrl`, `name` and uppercase platforms), and the
+  URL is RTMP or RTMPS only (the SDK allowed SRT, which the backend refuses).
+- **`sdk.getChatStatus(tokenName)`** (`GET /live/:tokenName/chat`, public): `{ enabled, tokenName,
+  reason?, slowModeSeconds?, status? }`. `ChatStatusResponse` gains `tokenName` and `slowModeSeconds`.
+- **The pinned message is the backend's `PinnedMessageData`** (`messageId`, `content`, `userAddress`,
+  `pinnedBy`, `pinnedAt`, `user?`, `holderTier?`): `getPinnedMessage` returned a type with `id` and
+  `createdAt` the backend never sends, and threw when nothing was pinned (`{ data: null }`); it returns
+  `{ message: null }` now. `getPinnedChatMessage` / `pinChatMessage` return that message as it is, and
+  `unpinChatMessage` takes its `messageId`.
+- **`UpdateMessageOptions.type`**: a chat edit is capped at 500 characters before it is sent when the
+  type is known (`updateChatMessage` passes it).
+- **`PoolData` names the streaming fields the backend sends**: `muxPlaybackId`, `muxStreamAspectRatio`,
+  `streamLanguage` (typed `playbackId`, `aspectRatio`, `language`, which the backend does not send, so
+  they were always undefined); `streamEnabled`, `messagesEnabled`, `commentsEnabled` are not on a pool.
+- **New `sdk.getUserGalaBalance(address)`** (`GET /v1/users/:address/gala-balance`, public: the GALA
+  balance and USD value the backend reads) and **`sdk.fetchReferralCode()`**
+  (`GET /v1/connect/users/referrals/code`, JWT: `{ code, username? }`).
+- **`TradesQueryResult` is the one trades result type, and it is not deprecated.** `getTrades`,
+  `getRecentTrades` and `getHolderHistory` return the backend's `{ trades, pageInfo }`; the
+  `@deprecated` marker (it pointed at `TradesListResult`, an `items`/`meta` type no method returns) and
+  `TradesListResult` are gone, and the `getTrades` examples read `pageInfo` (they destructured a `meta`
+  the result never had).
+- **`UpdateTokenConfigOptions` is one type.** The package root exported a `token-config.dto` interface
+  (social links `string` only) while `updateTokenConfig` took a second one declared beside the message
+  types (`string | null`). The backend's `UpdateTokenConfigDto` takes `null` to clear a social link, so
+  the one type is the `string | null` form, declared in `token-config.dto` with
+  `validateUpdateTokenConfigOptions` (moved with it), and the dead duplicate
+  `InternalUpdateTokenConfigResponse` of `messages.dto` is gone.
+- **The pin and invite result types are exported, one meaning per name.** `pinMessage` / `unpinMessage`
+  return `PinMessageResult` (`{ success }`) and `getPinnedMessage` returns `PinnedMessageResult`
+  (`{ message }`), both now exported from the root; the root's old `PinMessageResult`
+  (`{ tokenName, pinnedMessage }`, the shape of a removed REST route) is gone and
+  `getPinnedChatMessage` / `pinChatMessage` return `GetPinnedMessageResult`
+  (`pinnedMessage` is `null` when another moderator unpinned between the pin and the read back; it was
+  cast to non-null). `InviteScope`, `UpdateInviteRoleOptions` and `UpdateInviteRoleResult` are exported;
+  the identical `InviteScope` of `streaming.dto` and `ModeratedTokenInviteScope` are the one
+  `InviteScope`.
+- **`fetchProfile` is typed and unwrapped.** `fetchProfile(address)` returned the whole
+  `{ status, error, message, data }` envelope typed `unknown`; it returns `PublicUserProfile` (the
+  backend's `ProfileResponse`: `address`, nullable `fullName` / `profileImage` / `bio`, `stats`
+  (`ProfileStats`), the four `BadgeStatus[]` ladders, `isLiveStreaming`, `liveStreamToken`) and a body
+  that is not that shape is a `NetworkError` (`Malformed profile response`). The service's no-address
+  form (`GET /v1/users/me/profile`, JWT) returns `CurrentUserProfile`. `BadgeStatus`, `ProfileStats`,
+  `PublicUserProfile` and `CurrentUserProfile` are exported.
+- **`PoolData` types `badges`** (`PoolBadges`: the `volume` and `engagement` `BadgeStatus[]` ladders the
+  backend builds for `GET /v1/tokens` and `/:tokenName`) and the stored `volumeBadge` / `engagementBadge`
+  columns. The pool route sends no `chatEnabled`, `streamingEnabled` or `tokenSymbol` (they are not in
+  its attribute list), so `PoolData` does not declare them.
+- **Message, comment and chat types are the backend's five shapes** (`GET /v1/messages` and the four write
+  answers differ; the SDK typed one invented `BaseContentItem` for all of them). `Message` is the list
+  item of `fetchMessages`, `getComments` and `getChatMessages`: `id` and `messageId` (the same string),
+  `user` / `userProfile` (the same non-null `{ fullName, profileImage }`), `updatedAt` `string | null`,
+  `reactions: { counts, userReacted? }` (was a plain `Record<string, number>`), and no `type`,
+  `holderTier` or `isPinned` (the backend sends none of them on a list item). Writes: `sendChatMessage`
+  returns `SentChatMessage` (no database id, `holderTier?`), `createComment` / `updateComment` return
+  `WrittenComment` (numeric `id` AND `messageId`, no `tokenName`), `updateChatMessage` returns
+  `EditedChatMessage` (numeric `id`, `reactions?` as `ReactionData`); `createMessage` / `updateMessage`
+  infer the result from `options.type`. `BaseContentItem`, `CommentItem`, `ChatMessageItem`,
+  `isChatMessageItem` and the dead `/v1/comments` result types (`CommentData`, `FetchCommentsResult`,
+  `PostCommentResult`, `FetchCommentsOptions`, `PostCommentOptions`, `DeleteCommentOptions`, file
+  `comment.dto.ts`) are gone; `isMessage` checks the real shape (it needed a `type` no item has, so it
+  was false for every item). Each id the examples took from a write (`result.comment.id`, a number, or
+  `result.message.id`, undefined) is the `messageId`.
+- **Each method validates the token name of ITS backend route** (launchpad-backend origin/main). The SDK
+  refused names the routes take (3-20 everywhere, 2-20 on messages, 50 on trades) and sent names a route
+  refuses. Five rules, exported as `TOKEN_NAME_*_CONSTRAINT` (and `TokenNameConstraint`), replace
+  `LAUNCHPAD_TOKEN_NAME_CONSTRAINT`, `RELAXED_TOKEN_NAME_CONSTRAINT`, `EXTENDED_TOKEN_NAME_CONSTRAINT`
+  and the helpers' silent 3-20 default (`validateTokenName(name, field, constraint)`,
+  `isValidTokenName(name, constraint)`, `validateOptionalTokenName(...)` now take the route's rule):
+  `DTO` 1-25 letters and digits (1-20 until rc.2; `@TokenNameField()` request fields: `fetchPools` filter, `fetchVolumeData`,
+  `fetchTokenDistribution`, `fetchUserHolderContext`, `fetchMessages`, `createMessage`, `getTrades`,
+  flag create, moderator invites, `banToken`), `FILTER` 1-50 (the flag lists), `PATH` letters and digits
+  1-255 (a raw `:tokenName` the pool lookup resolves, no format check: `fetchToken`, `fetchTokenStats`,
+  `updateTokenConfig`, `getTokenConfig`, image upload, every stream, recording, simulcast, ban and chat
+  method, `getPinnedMessage`, the user token list filter), `AVAILABILITY` 1-50 characters, any
+  (`validateToken`, `checkPool`: `ValidateTokenDto`), `EVENT` 1-100 characters without HTML (the
+  `WebSocketAdminService` emits). The root helpers `validateTokenName(name, field, constraint)`,
+  `isValidTokenName(name, constraint)` and `validateOptionalTokenName(name, field, constraint)` take the
+  rule of the route you name (they had a silent 3-20 default). The chain's launch rule (letters and
+  digits, 1+, no cap; what the launch form and `createSale` take) is `tokenNameSchema`,
+  `launchTokenDataSchema` and `imageUploadOptionsSchema`; `graphDataOptionsSchema` and
+  `graduateTokenOptionsSchema` use the DTO rule (`dtoTokenNameSchema`) and `checkPoolOptionsSchema` the
+  availability rule (`availabilityTokenNameSchema`). `TRADES_QUERY_CONSTRAINTS` (a deprecated
+  composite) is gone.
+- **The reaction routes take no token name.** `AddReactionDto` is `{ messageId, reactionType }` and the
+  backend refuses any other property (whitelist + forbidNonWhitelisted), so `addContentReaction` with a
+  `tokenName` answered 400; `AddContentReactionOptions` / `RemoveContentReactionOptions` lose
+  `tokenName` and nothing is validated or sent for it.
+- **`uploadTokenImage` and `uploadProfileImage` work on a signer-plus-address SDK.** The facade threw
+  "Wallet is required" (and `uploadProfileImage` defaulted the address from the wallet) though
+  `POST /v1/tokens/:tokenName/image` and `POST /v1/users/me/image` read the user from the session JWT and
+  need nothing else; an app configured with `{ signer, walletAddress, session }` and no `wallet` uploads
+  with the session bearer (`tests/g7-uploads-wire.test.ts`). `uploadProfileImage` no longer invents an
+  address: one that is given is validated and left out of the request. Their JSDoc described
+  `imagePath` options and a Node-only API that do not exist (the options are `{ file }`).
+- **Image uploads send multipart, not JSON.** Both uploads put the `FormData` through an axios instance
+  that carries `Content-Type: application/json` as an instance default; the request-level header was only
+  left out, so the default survived the merge and axios serialised the body as JSON
+  (`{"image":{}}`, the file lost; the 400 the backend answers was the only sign). `HttpClient` now
+  clears the Content-Type for a `FormData` body per request (an explicit `undefined`), so the transport
+  sets `multipart/form-data` with its boundary (axios' Node adapter, the browser's XHR). The existing
+  wire tests swapped the whole instance for one without the default and could not see it;
+  `tests/image-upload-multipart-wire.test.ts` (Node, real server) and
+  `tests/image-upload-multipart-browser-wire.test.ts` (jsdom XHR, real server, plus the FormData as it
+  leaves axios) run the real `createHttpExecutor` instance and read the bytes sent. These are the only
+  two multipart paths in the SDK.
+- **One name for an image upload.** `UploadImageByTokenNameOptions.options.tokenName` (a second name that
+  went into the URL without being validated) is gone; the path takes the validated `tokenName`. The dead
+  `LaunchpadAPI.uploadImageByTokenName` (`POST /launchpad/upload-image`) and
+  `LaunchpadAPI.fetchTokenDistribution` (`GET /holders/:tokenName`), routes the backend does not have, are
+  removed with their tests (`ImageService` and `PoolService` are the working ones).
+
+### The stream socket: one registry of subscribers (launchpad-backend origin/main)
+
+`StreamWebSocketService` keeps ONE registry. `sdk.realtime` is the service of an SDK (built with
+`streamWebSocketUrl`, the reconnect settings and the session's token). Every event the backend emits has a
+typed entry on it (`RealtimeEventPayloads`, read from the emit sites, not from the backend's docs).
+
+- **Any number of subscribers per event, per token, per room.** Every `subscribe*` method is synchronous,
+  returns that subscriber's OWN unsubscribe (a second call is harmless) and replaces nobody. The old
+  single callback slots (`globalCallbacks`, `roomCallbacks`, `globalFeedCallbacks`) are gone: a second
+  subscriber used to replace the first and the first's cleanup deleted the second's callback, and
+  `subscribeToStream` on a joined token wiped every other subscriber's callbacks. A subscriber that
+  throws or rejects is logged and skipped; the others are served. `LaunchpadSDK.watch*` are plain
+  subscribers (the fan-out, refcount and room bookkeeping `watchTokenRoomEvent` kept is deleted).
+- **Rooms are refcounted.** A token room, a comment room, the global feed and the events firehose are
+  joined on the FIRST subscriber and left on the LAST; never two server subscriptions for one room. A
+  leave waits for the join's acknowledgement (a subscribe followed at once by an unsubscribe cannot strand
+  the room on the server). A subscribe before the socket is connected registers and joins on connect; with
+  `autoConnect` (default) it also opens the socket. It never throws `NOT_CONNECTED`.
+- **Listeners are registered once per socket**, when it is created (they used to be registered again on
+  every `connect`, so every reconnect doubled every callback), and removed when it is closed.
+- **Reconnect.** The service acts on the Socket's `connect` (the Manager's `reconnect` fires before the
+  socket is connected and used to run `authenticate()` too early). On every connection after the first:
+  re-authenticate FIRST with the token current at that moment (`tokenProvider`, never a remembered
+  one) if the socket was authenticated, THEN re-join every room that still has a subscriber, THEN call the
+  new `onReconnect(listener)` listeners (the app's version never fired, `reconnect` is a Manager event).
+  `onConnectionStateChange(listener)` is new. A server-side `io server disconnect` reconnects (socket.io
+  does not), and so do `connect()` and a new subscribe after socket.io ran out of reconnection attempts
+  (`socket.active` stays true then). `LaunchpadSDKConfig.streamReconnectAttempts` / `streamReconnectDelay` /
+  `streamReconnectDelayMax` reach socket.io (a browser app wants `Infinity`, 1000, 10000); defaults stay
+  5 / 2000.
+- **`authenticate(token?)` returns `Promise<boolean>`** (it returned `void` and threw `NOT_CONNECTED`
+  when not connected): `true` on `authenticated`; `false` on `exception`, `stream_chat_auth_error`, the
+  10 s timeout, a dropped connection, no token, or a newer `authenticate` / `deauthenticate`. The same
+  token on the same connection sends nothing; a different token replaces the pending one and is sent after
+  the server answered the one in flight. `LaunchpadSDK.authenticateStreamWebSocket(token?)` takes the
+  app's token (or the session's) and returns the boolean. The handshake carries no token any more
+  (`StreamWebSocketConfig.authToken` is gone; a static token was presented, expired, on every reconnect).
+- **`deauthenticate()`** (`sdk.deauthenticateStreamWebSocket()`): the server has no message that drops a
+  socket's identity, so an authenticated socket is closed and opened again (subscriptions stay registered;
+  `onReconnect` fires). `setWallet` / `setWalletProvider` call it.
+- **`joinTokenRoom(token)`** holds a token's room with no listener (the room stays joined while its
+  listeners come and go); it returns its own release.
+- **The overseers' firehose** (`subscribeEventsFirehose(listener, filters?)`): one server subscription
+  for all subscribers, joined once the socket is authenticated (it is overseer-only) and again after every
+  re-authentication. The backend's firehose takes no filters, so each subscriber's
+  `{ eventTypes, tokenName, userAddress }` filters are applied client-side.
+- **The comment room.** `COMMENT_*` events are sent to the comment room only; `subscribeCommentCreated`
+  (and the new `Updated` / `Deleted`) now emit `subscribe_comment` (it never did, so it received nothing).
+- **User-room and overseer events are delivered to global subscribers** (`subscribeGlobalModeratorAdded`
+  / `Removed` / `RoleUpdated` / `InviteCreated`, `subscribeGlobalTokenBanned` / `Unbanned`,
+  `subscribeContentFlagged`, `subscribeFlagResolved`, `subscribeAIModerationComplete` / `Failed`,
+  `subscribeUserBanned` / `Unbanned`, `subscribeBanEnforcement`, `subscribeTradeUpdateNotify`,
+  `subscribeBalanceUpdated(token)`, ...), not only to a token room's subscribers.
+- **Feed subscribers are served whether or not the token room is joined.** The backend sends a client in
+  both rooms one copy of an event; the service delivers it to the token subscribers and to the feed
+  subscribers (it used to deliver it to the token room only, never to the feed).
+- **New events with typed payloads**: `STREAM_CHAT_UPDATED`, `STREAM_CHAT_DELETED`, `SLOW_MODE_CHANGED`,
+  `RECORDING_STATUS`, `RECORDINGS_COUNT_UPDATED`, `SIMULCAST_STATUS`, `DOWNLOAD_READY`,
+  `STREAM_CONTROL_STATUS_CHANGED`, `CONTENT_REACTION_ADDED` / `REMOVED`, `COMMENT_UPDATED` / `DELETED`,
+  `CONTENT_FLAGGED`, `FLAG_RESOLVED`, `AI_MODERATION_COMPLETE` / `FAILED`, `POOL_CREATED`,
+  `TRADE_UPDATE_NOTIFY`, `AI_MODERATION_GLOBAL_STATUS`, `EVENT` (firehose), `exception`.
+  `STREAM_COUNTDOWN_UPDATED` / `STREAM_LANGUAGE_UPDATED` are fed from `TOKEN_CONFIG_UPDATED` (the backend no
+  longer emits them separately). `getSiteConfigState()` returns the latest site-wide switches.
+  `subscribeFeedTokenEvents(cb)` hands every feed token event over named (`{ event, data }`).
+- **A second copy of one occurrence is dropped** for the events the backend sends through two rooms a
+  client can be in (`CONTENT_FLAGGED`, `FLAG_RESOLVED`, `AI_MODERATION_*`, `POOL_CREATED`, `OVERSEER_*`):
+  within 5 seconds, by id.
+- **A payload with no usable `tokenName` no longer throws inside the socket listener** (`data.tokenName.trim()`,
+  `data.content.slice`); it reaches the subscribers of the event for every token and none of a token.
+- **The 30-second replay buffer is removed.** It replayed stale events (trade deltas, candles) to a
+  late subscriber as if they were new, and started a timer per event per token; registration now precedes
+  the join, so there is no join race left for it to cover.
+- **Replaced APIs (9.0.0 is unpublished: no shims).** `setGlobalCallbacks` -> `addCallbacks(callbacks)`
+  (adds, returns the remover); `setGlobalFeedCallbacks`, `unsubscribeFromGlobalFeed` and the Promise form
+  of `subscribeToGlobalFeed` -> `subscribeToGlobalFeed(callbacks)` returns an unsubscribe;
+  `connectStreamWebSocket(callbacks)` adds subscribers; `subscribeToStream(token, callbacks)` adds, and
+  `unsubscribeFromStream(token)` removes only what `subscribeToStream` added. `subscribeEngagementStatsUpdated`
+  takes a token. `StreamingEventService` and its `streaming-events` types are deleted: the
+  `LaunchpadSDK.on*` methods they backed never fired (nothing fed them); they are now subscribers of the same
+  registry (`onStreamChatMessage`, `onViewerCountChanged`, `onUserBanned`, ...: every occurrence the socket
+  receives, for any token; join rooms with the `subscribe*` methods or `subscribeToStream`).
+  `disconnect()` releases every subscriber, listener and timer and rejects what is pending; the service can be
+  used again; `dispose()` (called by `sdk.cleanup()`) is final.
+- **Payload types follow the backend**: `UserBannedEvent` / `UserUnbannedEvent` / `BanEnforcementEvent`
+  (`isGlobal`, `isPermanent`, optional `reason` / `expiresAt` / `userAddress`; `tokenName` is `null` for a
+  global ban; the type guards accept the banned user's own copy, which has no address),
+  `TradeExecutedEvent` (+ `symbol`, `icon`), `BalanceUpdatedEvent` (the backend sends no balances),
+  `StreamGlobalStatusEvent` / `StreamChatGlobalStatusEvent` (`updatedAt` optional: `{ enabled }`), and the
+  global-feed token types are the token-room types (the feed copies named other fields). `COMMENT_DELETED`
+  carries `commentId`, not `messageId`.
+
 ### Fixes
 
+- `createSale`'s pre-flight refused launches the launch form and the deployed bundler accept (a
+  scheme-less link such as `t.me/x`, a lower-case symbol, a name of 2 or 21-25 characters, a
+  pre-buy of `5.`). It now refuses only what the bundler (fee window, bad words) or the chain
+  (`CreateTokenSaleDTO`, `TokenClass`) refuses: a name of letters and digits (any length), a symbol
+  of letters and digits in any case (the chain upper-cases it; the wire carries it as typed), no
+  link rules, a non-empty description (at most 1000) and image (at most 500), an integer
+  `saleStartTime`, and a plain-decimal pre-buy and curve portions, which are SIGNED in their
+  canonical spelling (`5.` -> `5`, `1.50` -> `1.5`: the chain keeps any other spelling a string
+  and refuses it). Bad words are still refused by the bundler after signing (it fetches the list).
+  `LaunchpadTradeInput`, `LaunchpadExtraFees` and `CreateSaleInput` are exported by name
+  (`@since 9.0.0`), and `LaunchpadTradeInput.extraFees` documents what is sent on a buy.
+- `BundleSubmission.wait()` takes `{ signal?: AbortSignal }` beside `timeoutMs` / `pollIntervalMs`
+  (`@since 9.0.0`). An aborted wait rejects with `LaunchpadSDKError` `BUNDLE_WAIT_ABORTED`
+  (`details.method`, `details.bundleId`; an already aborted signal rejects before a socket is opened
+  or a read sent) and stops what it started: the in-flight read (the requestor gets the wait's
+  `AbortSignal` as `init.signal`), the pause between reads, the deadline timer, its socket listener
+  (an own socket is disconnected, a borrowed `bundleSocketFactory` socket never). Aborting stops
+  watching only; `attach` resumes the bundle. A wait that ends for any reason now stops its reads too
+  (they used to run on until the deadline, up to 10 minutes). Also: one failed confirmation read (an
+  HTTP error, a network error, an unreadable body) no longer rejects the wait with
+  `BUNDLE_REQUEST_FAILED` while the socket can still deliver: reads are repeated every
+  `pollIntervalMs` until the deadline, and only a verdict (PROCESSED / FAILED), the deadline or an
+  abort ends the wait. At the deadline after failing reads the error is `BUNDLE_CONFIRMATION_TIMEOUT`
+  with the last failed read in `details.lastReadFailure` (`{ message, status? }`); the deadline
+  also holds for a read that never answers.
 - `graduateToken` bought `calculateBuyAmountForGraduation`'s `amount` (the GALA cost of the
   remaining tokens) as the exact-buy token quantity. It buys `remainingTokens`, with the GALA cost
   as `expectedAmount` (the slippage cap).

package/EXAMPLES.md

@@ -53,7 +53,7 @@ Q: What operation am I performing?
 
 | Format | Pattern | Example | Used For |
 |--------|---------|---------|----------|
-| **tokenName** | Simple lowercase, 3-20 chars | `'anime'` | Bonding curve ops, price |
+| **tokenName** | Letters and digits, 1-25 chars | `'anime'` | Bonding curve ops, price |
 | **token id / class key** | `collection\|category\|type\|additionalKey` | `'GALA\|Unit\|none\|none'` | Transfers, balances, locks, standard tokens |
 
 ### Common Mistakes Table