glitch-javascript-sdk 3.10.8 → 3.15.0

package/guides/microtransactions.md

@@ -0,0 +1,385 @@
+# Game microtransactions
+
+**Minimum SDK for this guide: `3.15.0`.** Use a confirmed published `3.15.0+`
+release or an approved local package. Registry verification on September 15, 2026
+showed public latest `3.10.8`, which lacks commerce; a plain public npm install at
+that point cannot run this callback/history example. Until `3.15.0` is actually
+published, use only the reviewed local `glitch-javascript-sdk-3.15.0.tgz` for testing.
+Do not change a production dependency to an unpublished version or assume that
+local build success means public publication has happened.
+
+The SDK entry point is `Glitch.api.Microtransactions`. All HTTP methods return an
+Axios response whose `response.data.data` contains the typed commerce result.
+Configure the ordinary API base once using the existing Glitch configuration.
+Never put a developer/MCP/install token into a shipped browser game.
+
+## Developer setup
+
+1. Read `settings`, `readiness`, `providers` and `listProducts` with a signed-in
+   title administrator. Start disabled/sandbox. Approvals are server-controlled.
+   The **Enable in-game purchases** and **Show ads** switches live only on the
+   game's Pricing/monetization page. Microtransactions is for products, media,
+   prices, orders and integration—not a second location for those switches.
+2. `uploadMedia(titleId, file, onProgress?)` reuses existing Glitch Media with
+   trusted title/actor ownership. Attach returned `id` to `media_ids` or
+   `branding.logo_media_id`. No scheduler or social-library post is created.
+3. Create a product draft using `createProduct`. Prices use integer minor units,
+   not floating-point money: USD 499 means $4.99; JPY 499 means ¥499. Supported
+   currencies are USD/EUR/GBP/CAD/AUD/JPY/BRL/INR/KRW; provider coverage can be
+   narrower. Each price is 1–100000 minor units, with country `US` or `*` fallback.
+   Provider-specific purchase minima are checked separately (sandbox USD: 50).
+4. Product types are durable, consumable, currency, bundle or pass. Grants have
+   a stable key, quantity and kind. Durable quantity is one. Pass requires
+   `duration_seconds` between 60 and 31536000, with no active stacking. Existing
+   purchased grants cannot be changed in place: create a new SKU. No recurring
+   subscriptions, gifts, paid random loot, cash-out or cross-game wallet support.
+5. Configure the exact game origin, regions/currencies, support contact and
+   game name/accent/logo with `updateSettings`. The fixed commission is 1200bp
+   (12%) of discounted pre-tax subtotal. Actual provider costs are separate.
+   Taxes are separate; pending earnings are not a verified available payout.
+6. Run a real approved provider sandbox purchase, verify game delivery/claim,
+   then call `verifyIntegration(titleId, {order_id, confirm:true})`. This records
+   real evidence, not a self-certified integration checkbox. Launch still needs
+   independent seller/tax/provider approvals. MCP confirm alone cannot supply them.
+
+Product limits: SKU/grant key 1–100 alphanumeric/underscore/dot/hyphen characters;
+name 255 characters; description 4000; 10 distinct Media UUIDs; 50 prices; 30
+distinct grants; 30 localizations. Settings allow 20 exact origins (255 chars
+each), 100 countries and 20 supported currencies. Branding name maximum 100.
+Server capability schemas remain authoritative.
+
+Required product fields are **SKU\***, **Name\***, **Type\***, **Prices\*** and
+**Grants\***; each price needs currency, country and integer minor-unit amount,
+and each grant needs key, quantity and kind. A pass also needs duration in seconds.
+For a pack of **100 Timber** spent building things, choose product type `currency`
+(or `consumable`) and grant `{key:'timber',quantity:100,kind:'consumable'}`. A durable
+grant means lasting ownership and cannot be spent; it is wrong for building Timber.
+
+## Hosted checkout and account creation
+
+`createCheckoutSession(titleId, {product_id,quantity,country,currency,environment,
+channel:'web',return_origin,nonce})` is anonymous-safe and only opens the purchase
+flow. Use `createMicrotransactionNonce()` to generate the nonce and retain it in
+the game. `hosted_url` points to Glitch's game-branded checkout with the session
+secret in a `#token` fragment, never a query parameter.
+
+Use `openMicrotransactionOverlay` to mount an accessible modal iframe inside the
+running game, even if the game is itself embedded. The game document, URL,
+session, canvas and state remain intact. Do not navigate the game away for checkout
+or provide a top-level fallback. The iframe permits payments and controlled
+bank/OAuth verification windows but has no top-navigation sandbox permission.
+When embedding or required verification is unavailable, offer retry/close while
+preserving the game. Retry reloads only the same session, not a new charge.
+
+The overlay bounds each document-loading and application-ready wait to 20 seconds
+by default (`frameLoadTimeoutMs`, clamped to 1–60 seconds). A missing iframe load
+or error event cannot leave the player indefinitely at Loading. Timeout displays
+explicit Retry/Close guidance without initiating payment or navigating the game.
+A document `load` only starts the bounded application-ready wait; it is not proof
+that checkout rendered. The hosted page sends
+`{type:'glitch.microtransaction.ready',version:1,title_id,checkout_session_id,nonce}`
+only after its valid-session account/checkout UI is usable. Exact origin/source/
+session/nonce checks protect this signal, and it never grants inventory. Retry
+resets timers; verified readiness and close clear them.
+
+The read-only `getCheckoutFramePolicy(titleId,sessionId)` returns only approved
+`frame_ancestors` and expiry; the hosted document uses that server-owned policy.
+It does not expose a checkout token or player data.
+
+Inside Glitch, the page uses existing sign-in/registration/OAuth and binds the
+checkout session once to that user. Session methods require
+`{checkoutToken: sessionSecret}` as their last options argument. The existing
+signed-in account JWT stays inside Glitch, not the game. The SDK sends the limited
+session secret only in `X-Checkout-Token` and never temporarily changes global auth.
+
+`checkout(titleId, sessionId, {idempotency_key,accept_terms:true}, options)` returns
+an order, quote, provider and UI mode. Stripe uses `ui_mode:'embedded'`, a limited
+`client_secret` and public `publishable_key`; mount Stripe Embedded Checkout
+inside the branded page, never build custom raw card fields. Approved Xsolla
+routes use `ui_mode:'xsolla'` and its official Pay Station flow. Disclose payment
+methods that need external authentication.
+
+Stripe 3DS is part of checkout. Exercise challenge success, cancel/failure,
+timeout and reload in the real sandbox. Keep the same order/session/idempotency
+key through authentication. `action_required`, provider authorization, redirect,
+and client completion are not paid/delivered proof. Call
+`reconcileCheckoutSession(titleId, sessionId, options)` to query the original
+attempt; never charge another provider after an uncertain submission.
+
+## Verified game/account handoff
+
+After verified payment and fulfillment, `createHandoff` returns an event with
+`type:'glitch.microtransaction.updated'`, `version:1`, `title_id`,
+`checkout_session_id`, `order_id`, `nonce`, and a one-time `claim_code` valid for
+two minutes. The hosted page targets the exact approved game origin. It never
+posts the account JWT or a player token.
+
+The SDK does the secure return work for you: it checks the actual checkout iframe,
+origin, title, session and nonce, exchanges the one-time claim with Glitch, and
+then calls **your `onVerified` function with the server-verified result**. This is
+where your game connects the player account and displays the purchased inventory.
+You do not need to write your own `message` listener or grant items from a browser
+event. Closing checkout without a successful claim does not call this a purchase.
+
+### Minimal working Timber shop
+
+Copy this JavaScript module into your game's browser bundle. Call
+`installTimberShop` with the title/product IDs and API/checkout origins shown by
+your game integration settings. For local testing use your approved local origins
+and `allowLocalDevelopment:true`; for production use approved HTTPS endpoints.
+The example creates its own small UI, so no undefined HTML elements or game helper
+functions are required. It never takes the player away from the game.
+
+```js
+import Glitch, {
+  createMicrotransactionNonce,
+  openMicrotransactionOverlay,
+  openMicrotransactionRestoreOverlay,
+} from 'glitch-javascript-sdk';
+
+export function installTimberShop({ titleId, productId, apiBaseUrl, checkoutOrigin,
+  environment = 'sandbox', allowLocalDevelopment = false }) {
+  Glitch.util.Requests.setBaseUrl(apiBaseUrl); // Set API location, NOT global auth.
+  const api = Glitch.api.Microtransactions;
+  const game = { playerId: null, inventory: [], paused: false };
+  let playerToken = '', tokenExpiresAt = 0, overlay = null;
+  let opening = false, spending = false, pendingUse = null;
+  const shop = document.createElement('section');
+  const status = document.createElement('p'); status.setAttribute('role', 'status');
+  const timber = document.createElement('output');
+  const history = document.createElement('pre');
+  shop.append(timber, status, history); document.body.append(shop);
+  const say = text => { status.textContent = text; };
+
+  function replaceInventoryInYourGame(entitlements) {
+    game.inventory = entitlements; // REPLACE the snapshot. Never add 100 here.
+    timber.textContent = 'Timber: ' + (entitlements.find(x => x.key === 'timber')?.balance ?? 0);
+  }
+  function setGamePaused(paused) { game.paused = paused; }
+  function onVerified(result) {
+    game.playerId = result.player_id; // Associate the game's profile with this player.
+    playerToken = result.player_token; // Memory only; never a URL or global auth token.
+    tokenExpiresAt = Date.parse(result.expires_at);
+    replaceInventoryInYourGame(result.entitlements); // Already verified by Glitch.
+    say('Account connected. Your current inventory is ready.');
+  }
+  function playerOptions() {
+    if (!playerToken || Date.now() >= tokenExpiresAt) {
+      throw new Error('Player authentication is required; restore needs an active purchase.');
+    }
+    return { playerToken }; // Per-request token; never choose a user_id.
+  }
+  function showError(error) {
+    const code = error?.response?.data?.code ?? error?.code ?? error?.response?.data?.message;
+    const noRestore = code === 'no_purchases_to_restore'
+      || error?.response?.data?.message === 'No active purchases to restore for this game/account/environment.';
+    say(noRestore
+      ? 'No active purchases to restore. Refunded receipt history still belongs to this account, but no new game token or items can be granted here.'
+      : 'Not completed. Retry the same action. If sign-in expired, authenticate again; restore requires an active purchase.');
+  }
+  async function openShop(restore) {
+    if (opening || overlay) return;
+    opening = true;
+    try {
+      const context = { return_origin: window.location.origin,
+        nonce: createMicrotransactionNonce(), environment };
+      const response = restore
+        ? await api.createRestoreSession(titleId, context)
+        : await api.createCheckoutSession(titleId, { ...context, product_id: productId,
+          quantity: 1, country: 'US', currency: 'USD', channel: 'web' });
+      const open = restore ? openMicrotransactionRestoreOverlay : openMicrotransactionOverlay;
+      overlay = open({ titleId, checkoutOrigin, session: response.data.data,
+        allowLocalDevelopment, onVerified,
+        onOpen: () => setGamePaused(true),
+        onClose: () => { overlay = null; setGamePaused(false); },
+        onOrderUpdate: order => say(order ? 'Receipt: ' + order.payment_status : 'No completed receipt yet.'),
+        onError: showError });
+    } finally { opening = false; }
+  }
+  async function showMyPurchases(page = 1) {
+    const response = await api.listMyPurchases(titleId,
+      { environment, page, per_page: 20 }, playerOptions());
+    const data = response.data.data;
+    history.textContent = data.purchases.map(purchase => {
+      const name = purchase.product.name ?? purchase.product.sku ?? ('Purchase ' + purchase.id);
+      return name + '\n' + purchase.grant_usage.map(row => row.key + ': ' + row.usage_status
+        + '; promised ' + row.purchased_quantity + ', granted ' + row.granted_quantity
+        + ', consumed ' + row.consumed_quantity + ', usable ' + row.usable_quantity).join('\n');
+    }).join('\n\n') || 'No captured purchases yet.';
+    say('History page ' + data.pagination.page + ' of ' + data.pagination.last_page);
+  }
+  async function useTenTimber() {
+    if (spending || game.paused) return;
+    const options = playerOptions();
+    if (pendingUse && pendingUse.playerId !== game.playerId) {
+      throw new Error('Restore the original account before retrying its pending action.');
+    }
+    // Create ONCE for this gameplay intent. A failed retry keeps this same object.
+    pendingUse ??= { playerId: game.playerId, action_id: createMicrotransactionNonce(),
+      key: 'timber', quantity: 10 };
+    spending = true;
+    try {
+      await api.consume(titleId, { key: pendingUse.key, quantity: pendingUse.quantity,
+        action_id: pendingUse.action_id, environment }, options);
+      const current = await api.listEntitlements(titleId, { environment }, options);
+      replaceInventoryInYourGame(current.data.data.entitlements);
+      pendingUse = null; // Clear only after successful acknowledgement AND refresh.
+      say('10 Timber spent once. Inventory refreshed from Glitch.');
+    } finally { spending = false; } // Do not clear pendingUse on failure.
+  }
+  function button(label, action) {
+    const element = document.createElement('button');
+    element.type = 'button'; element.textContent = label;
+    element.onclick = () => void action().catch(showError);
+    shop.append(element);
+  }
+  replaceInventoryInYourGame([]);
+  button('Buy 100 Timber', () => openShop(false));
+  button('Restore purchases', () => openShop(true));
+  button('My purchases', () => showMyPurchases());
+  button('Use 10 Timber', useTenTimber); // Explicit gameplay action, NOT a purchase callback.
+  return game;
+}
+```
+
+Call `installTimberShop({titleId: YOUR_TITLE_ID, productId: YOUR_TIMBER_PRODUCT_ID,
+apiBaseUrl: YOUR_API_BASE, checkoutOrigin: YOUR_CHECKOUT_ORIGIN})` from your existing
+game initialization. These four capitalized names describe your configuration;
+replace them with the actual values, not credentials. `environment` is optional
+and defaults to sandbox. The example assumes an eligible US/USD price; choose a
+server-supported country/currency for your real player instead of guessing from IP.
+
+**`replaceInventoryInYourGame` and `setGamePaused` are example game functions, not
+SDK APIs.** Their working demo bodies update the displayed Timber and `game`
+object. In your game, replace those bodies with your engine's inventory assignment
+and pause/input/audio controls. Do not replace assignment with `+= productQuantity`:
+callbacks, restores and refreshes can occur more than once. The callback must never
+call `consume`; that state-changing API belongs to an explicit gameplay action.
+
+The sample retains `pendingUse` across failed button retries. For reload recovery,
+persist the nonsecret action intent and its account binding in your game's durable
+command queue, then retry the same action ID after sign-in. Never save the player
+token with it, invent a new ID for an uncertain retry, or infer a particular action's
+success from aggregate purchase-history totals. Coordinate actual building creation
+idempotently with that same gameplay action; the demo only spends the resource.
+
+The verified result is the actual claim DTO. The helper validates matching
+title/session/order and, on refresh, the same player. It ignores duplicate codes
+even after a network timeout because the server may already have consumed them.
+It does not grant items from window data or continuously poll. A close message
+uses `{type:'glitch.microtransaction.close',version:1,title_id,
+checkout_session_id,nonce}` and must match the same exact origin/source/session.
+The dialog remains mounted until an in-flight claim and inventory callback finish.
+Close before a successful claim can refresh limited receipt status only; show
+pending/restore guidance, never claim that a checkout capability grants inventory.
+
+`player_token` lasts 15 minutes and is restricted to one title/player/environment.
+Keep it in memory and pass `{playerToken}` per request to `getOrder`,
+`listEntitlements` and `consume`. Never install it in global `Glitch.util.Session`
+or `Requests.setAuthToken`, log it, or put it in URLs. The SDK's per-request
+headers prevent simultaneous account/checkout requests from overwriting auth.
+
+### Inventory, purchase history and usage are different
+
+Use `listEntitlements` to replace the current player inventory. Use the optional
+`listMyPurchases(titleId, {environment,page,per_page}, {playerToken})` to show the
+signed-in player's captured purchases and their lot-level usage; it does not grant
+items or let a game pick another `user_id` or `player_id`. A normal user JWT selects
+its own user; a `gl_player` token selects its bound title/player/environment and
+requires the exact approved Origin. MCP and install tokens cannot use this route.
+Admin `listOrders` remains a separate developer reporting API.
+
+Read `response.data.data`:
+
+- `title_id`, `player_id`, `environment`, `purchases`, and
+  `pagination:{page,per_page,total,last_page,has_more_pages}`.
+- `page` defaults to 1 (1–10000), `per_page` to 20 (1–100). Results are ordered by
+  `created_at DESC, id DESC`. Pass the next page number when `has_more_pages` is true.
+  No cursor or product filter exists. The HTTP API rejects unknown selectors with 422;
+  the SDK rejects invalid filter names/ranges before transport.
+- Each purchase includes the immutable product snapshot, payment/fulfillment state,
+  `grant_usage`, `has_consumed_grants`, and `has_usable_grants`. Captured purchases
+  remain visible after refund, dispute or quarantine; unpaid attempts are excluded.
+  Historical snapshots may have null product `sku`, `name`, `type`, or `version`;
+  show a receipt-ID fallback rather than inventing a current catalog value.
+- Each grant usage row has `grant_id` (nullable), `key`, `kind`,
+  `purchased_quantity`, `granted_quantity`, `acquired_quantity`, `remaining_quantity`,
+  `consumed_quantity`, `revoked_quantity`, `refunded_quantity`,
+  `unrecoverable_quantity`, `expires_at`, `expired`, `usable_quantity`, `is_used`,
+  and `usage_status`.
+
+`purchased_quantity` is what the frozen product promised (grant quantity × order
+quantity). `granted_quantity` and its alias `acquired_quantity` are what was actually
+granted. Without a lot, `grant_id` is null and actual granted/remaining/consumed
+quantities are zero even though promised quantity can be positive. Do not grant
+missing items just because purchase history lists the promised amount.
+
+For consumables, `consumed_quantity = acquired_quantity - remaining_quantity -
+revoked_quantity`. Refunded quantity is bounded `revoked_quantity +
+unrecoverable_quantity`; **unrecoverable overlaps consumed**, so never subtract it
+twice. Refund recovery is not gameplay use. Durable/pass `is_used` is **null** because
+ownership does not prove gameplay usage; inspect `usable_quantity` and `expired`
+instead. Statuses are `unused`, `partially_used`, `used_up`, `owned`, `expired`,
+`revoked`, `not_delivered`, or `unavailable`. Use the server's fields, not a locally
+invented “used” checkbox or a raw remaining count that ignores expiry/restrictions.
+
+After expiry/reload or a lost claim response, call the anonymous-safe
+`createRestoreSession(titleId,{return_origin,nonce,environment})` and pass its
+returned `intent:'restore'` session to `openMicrotransactionRestoreOverlay` with
+the same hooks shown above. The account signs in inside the modal, then Glitch
+selects an owned paid purchase and sends its verified handoff. No original receipt
+ID or account JWT is required from the game, and restore never calls `/checkout`.
+The new session ID is known before authentication and remains strictly pinned.
+Restoring cannot duplicate ownership or recreate spent consumables; fully refunded,
+unpaid or failed purchases cannot issue a paid handoff.
+
+Restore can issue a new game token only when this account still has an eligible
+active purchase. An account with only fully refunded items may receive
+`no_purchases_to_restore`; the hosted sign-in/restore UI or the example's error
+handler should explain that clearly. An expired scoped token still requires
+authentication. The owner JWT in a Glitch-authenticated context can read all
+captured history, and an existing valid scoped token can read the same history,
+but this example does not promise a new game token after every refund/expiry.
+Do not bypass that boundary, expose the account JWT to the game, repurchase just
+to obtain history access, or invent a read-only-authentication endpoint.
+
+Lower-level `createMicrotransactionBridge` remains available for existing in-game
+iframe implementations; pass the actual iframe's `contentWindow`. Its `refresh()`
+works only after a successful claim. The older JWT-only `restoreHandoff` and
+receipt-pinned `createMicrotransactionRestoreBridge` are specialized trusted
+hosted-account flows, not the default anonymous-game recovery path.
+
+## Gameplay, refunds and failures
+
+- Use server entitlements, not mutable cloud saves. `consume` atomically spends
+  consumable units with a unique gameplay `action_id`; reuse that ID for retries.
+  Free local gameplay cannot mint paid balances. Pass expiry is server-authoritative.
+- Keep payment, fulfillment and settlement independent. Paid can coexist with
+  pending server delivery. Replaying delivery reuses immutable IDs and never
+  grants twice. Provider and game messages are at-least-once delivery.
+- Earnings `transferred_minor` means money transferred to a provider balance,
+  not a confirmed bank deposit. Preserve `bank_payout_status` and reserve/reconciliation
+  fields; never relabel pending or transferred balances as paid bank payouts.
+- `requestRefund` is an owning account's support request. `refundOrder` requires
+  a separately approved financial administrator; pending/unknown is not completed.
+  Preserve historical orders and reverse commission proportionately. Refunds
+  use the original provider/account, not the currently preferred payment route.
+- Handle HTTP 401/403 for account/scope, 404 for unavailable or cross-title IDs,
+  409 for idempotency/state/approval conflicts, 410 for expired sessions/claims,
+  422 for invalid inputs/revenue policy, 429 for rate limits and 503 for provider
+  coverage. Do not retry a hard decline/fraud block through another provider.
+- Ads-off is an actual per-title delivery policy. The backend rejects removing
+  the final working revenue model. Provider outages leave ads off and existing
+  ownership intact. Sandbox products do not constitute production monetization.
+
+## MCP
+
+Use `mcpCapabilities` to discover exact schemas, abilities, approval flags and
+examples. `mcpOperation` always targets the authenticated MCP facade; it never
+uses a game's runtime token. `mcpUploadMedia` uses the same authorized Media
+pipeline. The companion `glitch-mcp` package supplies explicit tools, a
+`glitch://microtransactions/setup` resource, dynamic title schema resources and
+the `glitch_setup_microtransactions` prompt. A model must not auto-approve live
+prices, provider activation, financial actions or disabling the last revenue model.
+Developer MCP read tools do not impersonate players. The self-only runtime purchase
+history API is documented for game code, not exposed as an arbitrary-player MCP tool.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glitch-javascript-sdk",
-  "version": "3.10.8",
+  "version": "3.15.0",
   "description": "Javascript SDK for Glitch",
   "publishConfig": {
     "access": "public"
@@ -9,13 +9,15 @@
   "module": "dist/esm/index.js",
   "files": [
     "dist",
-    "src"
+    "src",
+    "guides"
   ],
   "types": "dist/index.d.ts",
   "scripts": {
-    "test": "node scripts/test-hosting-routes.cjs && node scripts/test-game-advertising-routes.cjs && node scripts/test-game-design-routes.cjs && node scripts/test-discord-media-routes.cjs && node scripts/test-user-email-delivery-routes.cjs && node scripts/test-game-show-ticket-routes.cjs",
+    "test": "node scripts/test-hosting-routes.cjs && node scripts/test-game-advertising-routes.cjs && node scripts/test-game-design-routes.cjs && node scripts/test-discord-media-routes.cjs && node scripts/test-user-email-delivery-routes.cjs && node scripts/test-game-show-ticket-routes.cjs && node scripts/test-festival-networking-routes.cjs && node scripts/test-microtransaction-routes.cjs && node scripts/test-microtransaction-overlay.cjs && node scripts/test-microtransaction-tutorial.cjs",
     "build": "rm -Rf dist && rollup -c --bundleConfigAsCjs",
-    "build-docs": "rm  -rf docs && typedoc  --tsconfig tsconfig.json src/"
+    "build-docs": "rm  -rf docs && typedoc  --tsconfig tsconfig.json src/",
+    "test:package": "node scripts/test-package-exports.cjs"
   },
   "author": "",
   "license": "ISC",
@@ -27,6 +29,7 @@
     "@types/isomorphic-form-data": "^2.0.4",
     "@types/node": "^20.10.5",
     "get-file-object-from-local-path": "^1.0.2",
+    "jsdom": "^26.1.0",
     "rollup": "^4.9.1",
     "rollup-plugin-dts": "^6.1.0",
     "rollup-plugin-node-builtins": "^2.1.2",

package/src/api/FestivalNetworking.ts

@@ -0,0 +1,216 @@
+import { AxiosProgressEvent, AxiosPromise, AxiosRequestConfig } from 'axios';
+import FestivalNetworkingRoute from '../routes/FestivalNetworkingRoute';
+import Requests from '../util/Requests';
+
+export type FestivalPostKind = 'discussion' | 'job' | 'talent';
+export type FestivalPostState = 'active' | 'locked' | 'archived' | 'hidden' | 'deleted' | 'removed' | 'paused' | 'filled' | 'expired' | 'closed';
+export type FestivalApplicationState = 'submitted' | 'viewed' | 'shortlisted' | 'interview' | 'accepted' | 'rejected' | 'withdrawn' | 'closed';
+export type FestivalWorkType = 'full_time' | 'part_time' | 'contract' | 'gig';
+export type FestivalRequestOptions = Pick<AxiosRequestConfig, 'signal' | 'timeout'>;
+
+export interface FestivalNetworkingSettings {
+    discussions_enabled: boolean;
+    jobs_enabled: boolean;
+    employer_posts_enabled: boolean;
+    talent_posts_enabled: boolean;
+    matching_enabled: boolean;
+    voting_enabled: boolean;
+    comments_enabled: boolean;
+    media_enabled: boolean;
+    /** Registration or a valid ticket is mandatory; cannot be disabled. */
+    require_registration: true;
+    public_viewing: false;
+    anonymous_enabled: false;
+    categories: string[];
+    skills: string[];
+}
+
+export interface FestivalPostInput {
+    kind: FestivalPostKind;
+    title: string;
+    /** Sanitized HTML from the shared WYSIWYG editor. */
+    content: string;
+    visibility?: 'public' | 'unlisted' | 'private';
+    category?: string | null;
+    tags?: string[];
+    skills?: string[];
+    preferred_skills?: string[];
+    job_types?: FestivalWorkType[];
+    company?: string | null;
+    organization_id?: string | null;
+    work_arrangement?: 'remote' | 'onsite' | 'hybrid' | null;
+    experience?: 'any' | 'entry' | 'junior' | 'mid' | 'senior' | 'lead' | null;
+    location?: string | null;
+    availability?: 'immediately' | 'within_30_days' | 'specific_date' | 'flexible' | 'unavailable';
+    availability_date?: string | null;
+    deadline?: string | null;
+    expires_at?: string | null;
+    compensation_type?: 'negotiable' | 'yearly' | 'monthly' | 'hourly' | 'flat_fee';
+    compensation_min?: number | null;
+    compensation_max?: number | null;
+    currency?: string | null;
+    portfolio_url?: string | null;
+    application_method?: 'internal' | 'external';
+    application_url?: string | null;
+    /** UserMedia IDs returned by uploadMedia, NOT Media IDs or clip-library selections. Max 8. */
+    media_ids?: string[];
+    public_compensation?: boolean;
+    public_location?: boolean;
+    public_availability?: boolean;
+    public_portfolio?: boolean;
+}
+
+export interface FestivalNetworkingFilters {
+    kind?: FestivalPostKind;
+    view?: 'all' | 'mine' | 'saved' | 'hidden' | 'comments';
+    sort?: 'new' | 'hot' | 'top' | 'discussed' | 'compensation' | 'deadline';
+    window?: 'today' | 'week' | 'month' | 'festival' | 'all';
+    q?: string;
+    category?: string;
+    skill?: string;
+    job_type?: FestivalWorkType;
+    arrangement?: 'remote' | 'onsite' | 'hybrid';
+    experience?: string;
+    location?: string;
+    company?: string;
+    availability?: string;
+    currency?: string;
+    compensation_type?: string;
+    min_compensation?: number;
+    tag?: string;
+    author?: string;
+    has_comments?: boolean;
+    has_portfolio?: boolean;
+    media_type?: 'image' | 'video';
+    page?: number;
+    per_page?: number;
+}
+
+export interface FestivalMediaUpload {
+    id: string;
+    user_media_id: string;
+    media_id: string;
+    url: string;
+    mime_type: string;
+    size: number;
+    title: string;
+    processing_status: 'completed' | 'pending' | 'processing' | 'failed';
+}
+
+export interface FestivalNetworkingProfile { id: string | null; name: string; }
+export interface FestivalNetworkingResponse<T> {
+    data: T;
+    message?: string;
+    meta?: { current_page: number; last_page: number; total?: number; };
+    has_access?: boolean;
+    can_manage?: boolean;
+    can_moderate?: boolean;
+    user?: FestivalNetworkingProfile | null;
+    show?: { id: string; name: string; };
+    audit?: Array<Record<string, unknown>>;
+}
+export interface FestivalPost {
+    id: string;
+    game_show_id: string;
+    parent_id: string | null;
+    kind: FestivalPostKind | 'comment';
+    title: string;
+    content: string;
+    state: FestivalPostState;
+    visibility: 'public' | 'unlisted' | 'private';
+    details: Partial<FestivalPostInput>;
+    author: FestivalNetworkingProfile | null;
+    created_at: string;
+    updated_at: string;
+    score: number;
+    my_vote: -1 | 0 | 1;
+    saved: boolean;
+    is_owner: boolean;
+    can_edit: boolean;
+    comment_count: number;
+    media: Array<{ id: string; user_media_id?: string | null; url: string; mime_type: string; title: string | null; }>;
+    my_application?: { id: string; status: FestivalApplicationState; } | null;
+    match?: { score: number; reasons: string[]; missing_required_skills: string[]; disclaimer: string; };
+}
+export interface FestivalApplicationInput { message?: string; portfolio?: string[]; }
+export interface FestivalConversation {
+    id: string;
+    festival_application_id: string;
+    can_send: boolean;
+    read_only_reason: string | null;
+    festival_context: { game_show_id: string; post_id: string | null; title: string; kind: FestivalPostKind; application_status: FestivalApplicationState } | null;
+    users: Array<{ id: string | null; display_name: string; avatar: string | null }>;
+    messages: Array<{ id: string; thread_id: string; user_id: string | null; message: string; client_message_id: string | null; created_at: string; updated_at: string; user: { id: string | null; display_name: string; avatar: string | null } }>;
+}
+export interface FestivalPreferences { notifications?: boolean; blocked_users?: string[]; blocked_companies?: string[]; }
+export interface FestivalReportInput {
+    reason: 'spam' | 'harassment' | 'hate' | 'sexual_content' | 'scam' | 'job_scam' | 'copyright' | 'malicious_link' | 'misleading' | 'other';
+    explanation?: string;
+}
+
+/** Festival-scoped discussions, talent, jobs, moderation and new owned media uploads. */
+export default class FestivalNetworking {
+    private static request<T>(name: string, show_id: string, data?: object, ids: Record<string, string> = {}, params?: object, options?: FestivalRequestOptions): AxiosPromise<FestivalNetworkingResponse<T>> {
+        const replacements = Object.fromEntries(Object.entries({ show_id, ...ids }).map(([key, id]) => [key, encodeURIComponent(id)]));
+        return Requests.processRoute<T>(FestivalNetworkingRoute.routes[name], data, replacements, params, options);
+    }
+
+    /** Read enabled tools and the current account's registration/ticket access. */
+    static settings<T = FestivalNetworkingSettings>(id: string, options?: FestivalRequestOptions) { return this.request<T>('settings', id, undefined, {}, undefined, options); }
+    /** Organizer-only settings update; admission remains mandatory. */
+    static updateSettings<T = FestivalNetworkingSettings>(id: string, data: Partial<FestivalNetworkingSettings>) { return this.request<T>('updateSettings', id, data); }
+    /** Search posts; compensation comparisons require currency and period. */
+    static listPosts<T = FestivalPost[]>(id: string, params?: FestivalNetworkingFilters, options?: FestivalRequestOptions) { return this.request<T>('listPosts', id, undefined, {}, params, options); }
+    /** Create a post with rich HTML and optional newly uploaded UserMedia IDs. */
+    static createPost<T = FestivalPost>(id: string, data: FestivalPostInput) { return this.request<T>('createPost', id, data); }
+    /** Direct links still require admission and content visibility permission. */
+    static getPost<T = FestivalPost>(id: string, post_id: string, options?: FestivalRequestOptions) { return this.request<T>('getPost', id, undefined, { post_id }, undefined, options); }
+    /** Edit or soft-delete via state; omit media_ids to preserve current attachments. */
+    static updatePost<T = FestivalPost>(id: string, post_id: string, data: Partial<FestivalPostInput> & { state?: FestivalPostState }) { return this.request<T>('updatePost', id, data, { post_id }); }
+    /** Paginated direct replies; fetch children to expand a thread. */
+    static listComments<T = FestivalPost[]>(id: string, post_id: string, params?: { page?: number }, options?: FestivalRequestOptions) { return this.request<T>('listComments', id, undefined, { post_id }, params, options); }
+    /** Add a rich-text reply, subject to locking and five-level nesting. */
+    static createComment<T = FestivalPost>(id: string, post_id: string, data: { content: string }) { return this.request<T>('createComment', id, data, { post_id }); }
+    /** Set, replace, or remove a vote/save/hide idempotently. */
+    static setInteraction<T = FestivalPost>(id: string, post_id: string, data: { action: 'vote' | 'saved' | 'hidden'; value: -1 | 0 | 1 }) { return this.request<T>('setInteraction', id, data, { post_id }); }
+    /** Apply or express interest once; the original listing is snapshotted. */
+    static apply<T = Record<string, unknown>>(id: string, post_id: string, data: FestivalApplicationInput) { return this.request<T>('apply', id, data, { post_id }); }
+    /** Discovery matches for the current user's own job/talent listing. */
+    static matches<T = FestivalPost[]>(id: string, post_id: string, params?: { page?: number }, options?: FestivalRequestOptions) { return this.request<T>('matches', id, undefined, { post_id }, params, options); }
+    /** Report suspicious content privately to festival moderators. */
+    static report<T = never>(id: string, post_id: string, data: FestivalReportInput) { return this.request<T>('report', id, data, { post_id }); }
+    /** Only the applicant and listing owner receive application records. */
+    static applications<T = Array<Record<string, unknown>>>(id: string, params?: { page?: number }, options?: FestivalRequestOptions) { return this.request<T>('applications', id, undefined, {}, params, options); }
+    /** Applicant withdrawal or owner-managed status changes. */
+    static updateApplication<T = Record<string, unknown>>(id: string, application_id: string, data: { status: Exclude<FestivalApplicationState, 'submitted'> }) { return this.request<T>('updateApplication', id, data, { application_id }); }
+    /** Open the application/talent inquiry's private shared-inbox conversation, creating it once for legacy applications. Only the applicant and original listing owner may call this. Use Messages.getThread/sendMessage for subsequent conversation activity. */
+    static conversation<T = FestivalConversation>(id: string, application_id: string) { return this.request<T>('conversation', id, {}, { application_id }); }
+    /** Moderator-only report queue and audit history. */
+    static moderation<T = Array<Record<string, unknown>>>(id: string, params?: { page?: number }, options?: FestivalRequestOptions) { return this.request<T>('moderation', id, undefined, {}, params, options); }
+    /** Moderation remains available even while the board is disabled. */
+    static moderatePost<T = FestivalPost>(id: string, post_id: string, data: { state?: 'active' | 'hidden' | 'locked' | 'deleted' | 'removed'; remove_media?: true }) { return this.request<T>('moderatePost', id, data, { post_id }); }
+    /** Resolve, dismiss or begin reviewing a report. */
+    static resolveReport<T = never>(id: string, report_id: string, data: { status: 'under_review' | 'resolved' | 'dismissed' }) { return this.request<T>('resolveReport', id, data, { report_id }); }
+    /** Moderator-only participant restrictions. */
+    static restrictMember<T = never>(id: string, user_id: string, data: { banned: boolean }) { return this.request<T>('restrictMember', id, data, { user_id }); }
+    /** Current user's privacy and notification preferences. */
+    static preferences<T = FestivalPreferences>(id: string, options?: FestivalRequestOptions) { return this.request<T>('preferences', id, undefined, {}, undefined, options); }
+    /** Set notification opt-out and blocked participants/companies. */
+    static updatePreferences<T = FestivalPreferences>(id: string, data: FestivalPreferences) { return this.request<T>('updatePreferences', id, data); }
+    /** Uploaded festival attachments only; not the gameplay clip library. */
+    static media<T = Array<Record<string, unknown>>>(id: string, params?: { page?: number }, options?: FestivalRequestOptions) { return this.request<T>('media', id, undefined, {}, params, options); }
+    /**
+     * Upload a new image (10 MB max) or video (100 MB max), using the existing media pipeline.
+     * The response ID is an owned UserMedia ID for createPost/updatePost media_ids.
+     * @param file New file selected by the attendee; supported images exclude SVG.
+     * @param data Which enabled board the upload is for.
+     * @param onUploadProgress Transfer progress; 100% may still require conversion before completion.
+     */
+    static uploadMedia<T = FestivalMediaUpload>(id: string, file: File | Blob, data: { kind: FestivalPostKind }, onUploadProgress?: (event: AxiosProgressEvent) => void, options?: FestivalRequestOptions): AxiosPromise<FestivalNetworkingResponse<T>> {
+        return Requests.uploadFile<T>(FestivalNetworkingRoute.routes.uploadMedia.url.replace('{show_id}', encodeURIComponent(id)), 'media', file, data, undefined, onUploadProgress, options);
+    }
+    /** Organizations the authenticated user is authorized to represent. */
+    static organizations<T = Array<{ id: string; name: string }>>(id: string, options?: FestivalRequestOptions) { return this.request<T>('organizations', id, undefined, {}, undefined, options); }
+    /** Organizer-only aggregate participation metrics. */
+    static analytics<T = Record<string, unknown>>(id: string, options?: FestivalRequestOptions) { return this.request<T>('analytics', id, undefined, {}, undefined, options); }
+}

package/src/api/Messages.ts

@@ -17,7 +17,10 @@ class Messages {
     }
 
     /**
-     * Send a new message that will be added to a thread
+     * Send a new message that will be added to a thread. Festival-scoped threads
+     * enforce current admission, blocking and read-only state server-side.
+     * Include an optional client_message_id UUID and reuse it when retrying a
+     * timed-out request to prevent duplicate messages and notifications.
      * 
      * @see https://api.glitch.fun/api/documentation#/Messages/storeMessage
      *