# ShowWeld TypeScript SDK Source package: `packages/showweld-sdk`. The manifest name is `@showweld/sdk`; this repository does **not** establish that the package is published on npm. Use the downloadable ES module when supplied by your ShowWeld deployment, or build this source locally. The module has no runtime package dependencies and uses native `fetch`, `Headers`, `AbortController`, and Web Crypto where available. Runtime exports: `ShowWeldClient`, `ShowWeld` (class alias), `createShowWeldClient`, and `ShowWeldApiError`. TypeScript interfaces are type-only exports. See [the SDK reference](REFERENCE.md) for endpoint, authentication, and error contracts. ## Server API keys Download the deployment's `/sdk/showweld-sdk.js` to your server project before using this example. Neither test nor live API keys belong in a browser, shipped mobile/desktop bundle, plugin manifest, public environment variable, or frontend source. Test keys are credentials against the real service, **not** offline fixtures. Provider keys, Stripe secret keys, webhook signing secrets, and database credentials never belong in SDK configuration. ```ts import { ShowWeldClient, ShowWeldApiError } from './showweld-sdk.js'; const apiKey = process.env.SHOWWELD_API_KEY; if (!apiKey) throw new Error('SHOWWELD_API_KEY is required'); const showweld = new ShowWeldClient({ apiKey }); const usage = await showweld.usage.get(); const projects = await showweld.projects.list(); ``` These API-key helpers use the existing `/api/developer.php?route=/v1/...` gateway. Supply a key with the scopes needed for each operation. Key creation/rotation, account auth, billing, and direct Spark video generation require website authentication and cannot be performed with an API-key client. Usage quotas roll over 24 hours, so `usage.periodResetAt` may be `null`; do not assume a midnight reset. The usage policy also identifies account-wide minute limits and enforced concurrency. Response/error metadata exposes `rateLimit.minuteLimit`, `minuteRemaining`, and `concurrencyLimit` separately from the daily request-unit `limit` and `remaining`. ## Website session ```ts import { ShowWeldClient } from '/sdk/showweld-sdk.js'; const showweld = new ShowWeldClient({ baseUrl: window.location.origin }); const projects = await showweld.projects.list(); ``` With no token, cookies default to `same-origin`. For a website session token supplied by your own authenticated application, use `{ accessToken: sessionToken, accessTokenType: 'session' }`. Token clients omit cookies. The SDK does not sign in, store credentials, refresh tokens, or handle OAuth redirects. Do not persist bearer tokens in browser storage as part of these examples. ## MCP OAuth / plugin integration ```ts import { ShowWeldClient } from './showweld-sdk.js'; const showweld = new ShowWeldClient({ accessToken: scopedMcpOAuthToken, accessTokenType: 'mcp', }); const catalog = await showweld.mcp.listTools(); const projects = await showweld.projects.list(); if (projects.length) { const result = await showweld.mcp.callTool('get_project', { project_id: projects[0].id, }); // Raw MCP result: content, structuredContent, isError, and _meta. } ``` An `accessToken` defaults to MCP OAuth. Website session tokens must explicitly set `accessTokenType: 'session'`. Developer API keys and MCP grants are not interchangeable. Acquire a resource-bound grant through the existing OAuth integration; this SDK is not a complete OAuth client or an Apps SDK widget bridge. Tool discovery provides the current inputs and approval requirements. Project wrappers return structured project data; `mcp.callTool()` preserves the raw tool envelope, and `mcp.toolData()` returns its `structuredContent`. ## Errors and request safety ```ts try { await showweld.projects.list(); } catch (error) { if (error instanceof ShowWeldApiError) { console.error(error.status, error.code, error.requestId); // retryAfterMs, rateLimit, and headers reflect what the server sent. // Do not replay a write or paid operation automatically. } else { throw error; // Network, cancellation, or configuration failure. } } ``` Automatic retries default to zero. Even with `retries` configured, a GET retries only when the individual request sets `retrySafe: true`; callers must establish that it cannot spend provider credits or mutate state. POST/PUT/PATCH/DELETE and MCP calls never retry automatically, including when an idempotency key is present. Some GET status/poll routes contact providers. An aborted or timed-out request may already have completed on the server. The SDK rejects cross-origin absolute request URLs and automatic redirects. Base URLs must use HTTPS, except loopback HTTP for development. Custom authorization/cookie headers are rejected; use the authentication options. Browser API-key construction is rejected as a misuse guard, not a replacement for protecting server secrets. ## Offline verification From the repository root: ```text node node_modules/typescript/bin/tsc -p packages/showweld-sdk/tsconfig.json --noEmit node scripts/paid-provider-test-guard.mjs --offline-node scripts/verify-showweld-sdk-offline.mjs ``` Or run `npm --prefix packages/showweld-sdk test`. The harness uses fake credentials and injected fetch responses, denies the real fetch transport, and checks selected PHP source contracts without executing PHP or connecting to a database. No provider/API/network request is made. Live paid tests require Ayjay's explicit authorization in the current task under `docs/PAID_AI_TEST_SAFETY.md`. Build with `npm --prefix packages/showweld-sdk run build` using the repository's installed TypeScript compiler. The output includes JavaScript and declarations in `dist`. Public download bundling and deployment are separate from this source package; no publication is performed by these commands.