@mythos-work/sdk

Official Mythos SDK for Node.js — launch token verification, OpenAI-compatible LLM access, usage reporting, and handshake.

Quick start

npm install @mythos-work/sdk
npx @mythos-work/sdk init
npx @mythos-work/sdk agents   # optional: skills for Claude Code, Cursor, Codex, Devin

import { createMythos } from '@mythos-work/sdk';

export const mythos = createMythos();
export const { GET, POST } = mythos.handlers;

const session = await mythos.getSession(req); // null in standalone mode
await mythos.charge(req, { credits: 1, reason: 'page-view' });
const client = await mythos.llm<OpenAI>(req, { apiKey: process.env.PRODUCER_OPENAI_API_KEY });
const billing = mythos.billing(completion);

Set MYTHOS_SESSION_SECRET to a random secret of at least 32 characters (openssl rand -base64 32). Node.js 20+ is required. See docs.mythos.work and the migration guide.

# openssl rand -base64 32  (>= 32 chars)
MYTHOS_SESSION_SECRET=
# Mythos dashboard → Settings → Mythos key
MYTHOS_KEY=

MYTHOS_KEY binds launch, handshake and callback tokens to your Producer: matching pkh accepts; missing or different pkh rejects with ProducerMismatchError (PRODUCER_MISMATCH, 401). Without a key, static MYTHOS_LISTING_ID(S) launches are silent safe legacy configuration; dynamic launches, handshake and callbacks warn once per process. A resolver or callback without a key warns at startup. Missing keys are soft in 0.5.0; required in 0.6.0. Regeneration requires updating deployment env and redeploying. See configuration and exact token contract.

| Troubleshooting code | Fix | |---|---| | PRODUCER_MISMATCH | The MYTHOS_KEY in this deployment belongs to a different Producer, or was regenerated. Copy the current key from the dashboard and redeploy. |

Browser

import { useMythos } from '@mythos-work/sdk/react';
const { status, session, fetch, confirmCharge, relaunch } = useMythos();
await confirmCharge({ credits: 1, reason: 'calculate' }); // fixed price
await confirmCharge({ kind: 'llm', reason: 'chat' });     // LLM: usage-based, no credits

For non-bundled pages:

<script src="https://cdn.jsdelivr.net/npm/@mythos-work/[email protected]/dist/mythos-client.global.js"></script>
<script>const m = Mythos.initMythos(); m.ready.then(console.log);</script>

Advanced (primitives)

Legacy sendHandshake and boolean-returning confirmCharge remain available from @mythos-work/sdk/client.

Install

npm install @mythos-work/sdk

OpenAI-compatible LLM

Use the session returned by requireLaunchToken() to create an official OpenAI client that routes through Mythos. The provider key is sent as the normal OpenAI Authorization header; the SDK adds the session identity header internally.

import { getLlmBillingMetadata, llm } from '@mythos-work/sdk/llm';

const client = llm(req.mythos, { apiKey: process.env.PROVIDER_API_KEY });
const completion = await client.chat.completions.create({
  model: 'openai/gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello' }],
});
const billing = getLlmBillingMetadata(completion);

If no session is available, pass { fallback } to return a fallback value unchanged; otherwise llm() throws MythosError. baseURL overrides the default ${MYTHOS_API_URL}/v1, and timeout is in milliseconds.

Quick start

import { requireLaunchToken, reportUsage, handshakeRoute, listingCallbackRoute } from '@mythos-work/sdk';
import express from 'express';

const app = express();
const listingIds = new Set<string>(); // populated by listingCallbackRoute

// Handshake endpoint — Mythos pings this before publishing your listing
app.use(handshakeRoute());

// Listing registration callback — Mythos calls this after your listing is registered
app.post('/.well-known/mythos-listing-registered', listingCallbackRoute(async (listingId) => {
  listingIds.add(listingId); // persist so resolveListingIds can read it
}));

// Protected route — verifies and consumes the launch token automatically
app.get(
  '/dashboard',
  requireLaunchToken({ resolveListingIds: async () => Array.from(listingIds) }),
  async (req, res) => {
    // req.mythos = { userId, email, displayName, listingId, sessionJti }
    await reportUsage(req.mythos.sessionJti, { credits: 1, reason: 'page-view' });
    res.json({ ok: true });
  },
);

Environment variables

| Variable | Required | Default | Description | | ----------------------| ----------| ---------------------------| -----------------------------------------------| | MYTHOS_SESSION_SECRET | Yes for createMythos | — | At least 32 characters; generate with openssl rand -base64 32 | | MYTHOS_KEY | Soft in 0.5.0 | — | Dashboard Producer key; required in 0.6.0 | | MYTHOS_LISTING_ID | No* | — | Your listing ID | | MYTHOS_LISTING_IDS | No* | — | Comma-separated listing IDs (overrides above) | | MYTHOS_API_URL | No | https://api.mythos.work | API base URL override |

*Optional when you provide resolveListingIds; otherwise one of MYTHOS_LISTING_ID or MYTHOS_LISTING_IDS is required.

API

requireLaunchToken({ resolveListingIds? })

Express middleware. Verifies the ES256 launch token from ?lt=, enforces single-use semantics, and attaches req.mythos to the request. Listing IDs are read from MYTHOS_LISTING_ID(S) by default; pass resolveListingIds to supply them dynamically (e.g. from storage populated by listingCallbackRoute). Returns 401 if the token is missing, invalid, or already consumed.

reportUsage(sessionJti, { credits, reason? })

Reports non-inference product fees against a session. Call after delivering value to the user; LLM inference is metered by the OpenAI-compatible gateway instead.

llm(session, { apiKey?, fallback?, baseURL?, timeout? })

Returns an official OpenAI client configured for the Mythos gateway and the session's identity. Use getLlmBillingMetadata(completion) to read server-provided billing metadata.

handshakeRoute()

Returns an Express Router that mounts GET /.well-known/mythos-handshake. Use app.use(handshakeRoute()) so the backend can reach the designated address during listing publish.

listingCallbackRoute(onRegistered)

Returns an Express RequestHandler. Mount it at the listing callback URL you configure. It validates the ?lt= token, calls onRegistered(listingId) on success, and responds with { ok: true }. Use the callback to persist the listing ID so resolveListingIds can read it. Returns 401 for missing/invalid tokens and 503 for unexpected errors.

verifyLaunchToken(token, { resolveListingIds? })

Low-level token verifier. Validates the launch token and returns the decoded MythosSession. Listing IDs are read from MYTHOS_LISTING_ID(S) by default; pass resolveListingIds to supply them dynamically. Use requireLaunchToken() middleware instead for most cases.

Security

• Tokens verified via ES256 against the Mythos JWKS endpoint
• alg: none rejected as a hard block
• Single-use enforcement is non-skippable (ADR-0003)
• JWKS keys cached 10 minutes with automatic re-fetch on key rotation

License

Apache-2.0 — see LICENSE.