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.
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".
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.
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
| Surface | Intended 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
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.
- Read context.
Find the authorized project, files, and current version.
- Propose the action.
Explain the change and applicable credit usage. Preserve existing approval boundaries.
- Use the specific tool.
Send bounded arguments that match the discovered schema.
- 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.
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.