Skip to content
ShowWeldDevelopers
BUILD / JAVASCRIPT & TYPESCRIPT

Less setup. Clearer boundaries.

A small client for ShowWeld’s existing API. Download the module, keep credentials on your server, and begin with a read-only request.

Current release referencePHP backend · Shared account controls

Start on your server

Download the ESM module and save it as showweld-sdk.mjs in your server project. The download is built from the SDK source shipped with this release. A public npm registry publication is not assumed. For TypeScript, save the declarations as showweld-sdk.d.mts beside the .mjs module, or keep the .js/.d.ts pair in a package with "type": "module".

Node.js · server-side only
import { ShowWeldClient } from './showweld-sdk.mjs';

const apiKey = process.env.SHOWWELD_API_KEY;
if (!apiKey) throw new Error('Configure SHOWWELD_API_KEY on your server');

const client = new ShowWeldClient({
  apiKey,
  timeoutMs: 15000,
  retries: 0
});

const usage = await client.usage.get();
console.log({ remaining: usage.remaining, limits: usage.rateLimits });

Use a current runtime with fetch and AbortController, or supply a compatible fetch implementation. The SDK makes no request just by constructing a client.

Use the right client for the job

Server integrations use apiKey. OAuth clients use accessToken for MCP. A same-origin, signed-in ShowWeld page may use the account session. Do not put a long-lived developer key in a React component or mobile app bundle.

OAuth client · token obtained through the user’s consent flow
const client = new ShowWeldClient({
  accessToken,
  accessTokenType: 'mcp',
  retries: 0,
  timeoutMs: 15000
});
const result = await client.mcp.callTool('list_projects', {});

Supply one credential mode, not both. Cross-origin frontend code should call your own backend, which validates the signed-in user and chooses the permitted operation. Never build a generic proxy that forwards arbitrary user-supplied URLs with your API key.

Read the method and its authority together

SurfaceIntended use
usage.get()Inspect quota and billing state for the selected supported authentication mode.
projects.list() / projects.get(id)Read authorized projects. Do not assume an arbitrary supplied project ID is accessible.
mcp.callTool(name, args)Invoke a discovered MCP tool with its current input schema and scope requirements. Inspect tool-level errors.
apiKeys.list/create/rotate/revoke()Account-session management; not authority available to a third-party developer key.
webhooks.list/create/delete()Manage callback registrations. See the documented outbound delivery limitation.
billing.createTokenPurchase()Authenticated owner checkout flow. It does not credit an account itself.
request(path, options)Advanced route access within the configured API origin. Keep path, credential type, method, and idempotency consistent with the backend.

The downloadable declarations and README describe the exact method signatures. Unsupported auth/route combinations must be handled as errors, not worked around by sending credentials elsewhere.

Handle errors without accidental spending

Application error handling
import { ShowWeldApiError } from './showweld-sdk.mjs';

try {
  const usage = await client.usage.get();
  // Display allowance and billing state in your own authenticated UI.
} catch (error) {
  if (error instanceof ShowWeldApiError) {
    console.error({ status: error.status, code: error.code, requestId: error.requestId });
    // Honor rate-limit metadata. Reconcile writes before retrying.
    // Do not log credentials, full response bodies, or private content.
  }
  throw error;
}

The client exposes retryAfterMs, rateLimit, and safe response headers. Retries default to zero. An explicitly enabled retry only applies to a GET marked retrySafe: true; MCP calls and writes never automatically retry. Configure timeouts and cancellation. Automatic retry must never repeat a mutating or paid call. If a network connection fails after submission, the server may already have accepted the work; inspect the operation before trying again.

Discover tools before orchestrating them

Use MCP discovery and OAuth for assistant integrations. The server defines current tool schemas, read/write annotations, and account scope requirements. Avoid copying a large hard-coded tool catalog into your agent prompt.

  1. Read context.

    Find the authorized project, files, and current version.

  2. Propose the action.

    Explain the change and applicable credit usage. Preserve existing approval boundaries.

  3. Use the specific tool.

    Send bounded arguments that match the discovered schema.

  4. Verify the result.

    Inspect saved state and actual artifacts. Report pending or partial work honestly.

Usage is visible; permission stays explicit

Call usage.get() before a large batch, but let the server make the final decision on every request. A preflight balance can change before execution. Keep batches bounded and stop on a denied or uncertain operation.

Payment, plan usage, AI credits, media reservations, and request capacity have different lifecycles. The SDK cannot infer a final provider charge from a token count or a queued job alone. Read the billing contract.

Ship with a narrow trust boundary

Pin your deployed SDK artifact, keep HTTPS on in production, and use separate least-privilege credentials for separate services. Restrict your own application’s users before invoking ShowWeld on their behalf.

Use mocked fetch responses and the downloaded type declarations in automated tests. Never attach a live funded key to an unattended test suite. Download the agent integration guide for a reusable implementation checklist.

Published app runtime

App Builder compiles a self-contained release for the StorySphere player. The app runs in an isolated frame and receives window.ShowWeld, without the account session or provider keys.

Browser JavaScript
await window.ShowWeld.ready;
const records = await window.ShowWeld.records.list('Notes');
await window.ShowWeld.records.save({ entity: 'Notes', recordKey: 'first', expectedVersion: 0, data: { title: 'A new note' } });
const products = await window.ShowWeld.commerce.products();
await window.ShowWeld.commerce.purchase('pro');

Declare collections in the app manifest. Saved records belong to the current user and app. Declare requiredProduct on a collection for server-checked paid access. A purchase opens a trusted review; it does not grant access until the server verifies payment.

Creator connections live in App Builder's publishing panel. Use ShowWeld.connections.call(name, input); users review the destination and input in the trusted host. Credentials stay encrypted on the PHP server. Never embed .env values or Stripe/provider keys in source. One-time web purchases use a 2% ShowWeld fee plus actual Stripe processing fees. Native digital checkout is unavailable until its store billing channel is configured.

Automatic app updates apply on the next launch; manual installs remain pinned. Browser installability varies, and online access is required for account data and entitlement checks.

Search authentication, plugins, webhooks, credits, or an endpoint.