SDKs

Install

Python and JavaScript 1.1.4, Go v1.0.0 and Playwright 0.1.0 are published. Use Quickstart for the first call and examples for the optional Python download helper.

Go and Playwright

Use the same prepared input contract. Go exposes NewClient,Usage(ctx), Generate(ctx, shape) and Close(). Its TargetRequest.Body and ContentType are string pointers: nil means JSON null; a pointer to an empty string preserves an empty value.

Playwright exposes RayonPlaywright, usage(),collectMaterial(page, options), generate(material, input)and close(). It wraps the JavaScript SDK and uses your existing page; it never launches a browser or sends the protected request automatically.

import { RayonPlaywright } from "rayon-sdk-playwright";

const apiKey = process.env.RAYON_API_KEY;
if (!apiKey) throw new Error("Set RAYON_API_KEY");
const client = new RayonPlaywright(apiKey);
try {
  console.log(await client.usage()); // Free check.
  const material = await client.collectMaterial(page, {
    scriptUrls: ["https://shop.example.com/protection.js?seed=observed"],
    action: async () => { await page.reload(); },
    // Opt in to includeDocumentCookie only if your protection needs it.
  });
  const result = await client.generate(material, {
    request: {
      url: "https://shop.example.com/api/check",
      method: "POST",
      content_type: "application/json",
      body: '{"username":"example_user"}',
    },
  });
  // Apply result.headers through your existing target integration.
} finally {
  await client.close();
}

Collection requires explicit script URLs in execution order and a caller action that produces their responses. Review that action before running it in an authenticated browser. Cookie capture is opt-in and excludes HttpOnly cookies. Prepared material can go directly to generate. Your browser, proxy, context and session remain under your control.

Client behavior

SDK 1.1.4 is published. Typed FormShapeResult supports mode: "form"; header results support optional a0. Follow Form payload integration for ordered body composition.

• Python: Client / AsyncClient, with with / async with.
• JavaScript: RayonClient; close it when done. Pass an AbortSignal to generate(shape, { signal }) for cancellation.
• Reuse one client across calls. Python and JavaScript clients validate inputs and reuse API connections and short-lived material references. They never fetch target scripts or cache headers/cookies.
• The default 45-second timeout is one monotonic budget for the whole call, including material refresh and any permitted retry.
• SDK 1.1.4 retains up to 128 script bundles and 16 MiB of serialized material per client, coalesces concurrent uploads of the same material and refreshes on the next real request within five seconds of expiry. There is no background billable generation.
• The only automatic generation retry is once after HTTP 422 material_expired with billing_status: not_charged, and only while the original scripts remain retained. All other errors, pending or unknown billing outcomes and transport failures are not automatically retried.

See material reuse for cache scope, limits and concurrent calls. Errors include a code, request ID and retry metadata. See Errors and limits.