The Playcode SDK

npm install @playcode/sdk

import { Playcode } from '@playcode/sdk'

const pc = new Playcode() // reads PLAYCODE_SECRET_KEY when a call needs it

Creating the client never throws and never calls the network: a missing key fails on the first call that needs it. Inside a Cloud app, the key is already in the environment.

The environment is read at call time, so values loaded after the client was created still count.

const { status, messageId } = await pc.email.send({
  to: 'anna@example.com',
  subject: 'Your invoice',
  html: '<p>Thank you!</p>',
  replyTo: 'support@example.com',
  idempotencyKey: invoice.id,
})

The answer's status is sending, held, captured or withheld: see Send email from your app. New values can appear, so treat an unknown one as not delivered yet. The SDK never retries a send by itself.

import { sendEmail } from '@playcode/sdk/email' gives the same call without the client.

const job = await pc.media.video({ prompt: 'A paper boat on a lake at dawn', quality: 'draft', idempotencyKey: id })
const { url } = await job.wait()

pc.media.video() starts a render and answers a job: job.wait() waits until the video is ready, 15 minutes at most by default, job.get() reads its state, and job.cancel() stops it. quality is standard, high or draft. The result is an address on Playcode, and each second of video is paid from the workspace's credits.

The app's key needs the media service for video: ask the agent to switch on media for the app. pc.media.image() is in the SDK too, but your app's key cannot use it yet: see Limits.

const pc = new Playcode({ apiToken: process.env.PLAYCODE_TOKEN })

const domain = await pc.api.domainGet({ domain: 'example.com' })
if (domain.uid) await pc.api.domainUpdate({ uid: domain.uid, input: { autoRenew: true } })

pc.api has one typed method for each operation of the API at the SDK's release. Its credential is an access token, never the app's secret key. Each write carries an Idempotency-Key, and the same key rides every retry: the client retries a network error, a 429 or a 5xx 2 times, so a retry never doubles a write. Pass your own key as the second argument: { idempotencyKey }. See The API and Access tokens and permissions.

import { verifyWebhook } from '@playcode/sdk'

const { id, event } = verifyWebhook({
  signature: req.headers['playcode-signature'],
  body: rawBody,
  secret: process.env.PLAYCODE_WEBHOOK_SECRET!,
})

Pass the raw request body, exactly as it arrived: a re-encoded body does not match the signature. It throws PlaycodeWebhookError for a bad signature, or a delivery older than 300 seconds (toleranceSeconds changes that). See Webhooks.

• The secret key stays on the server. A key in browser code is a leaked key: anyone who has it can send email and use AI as your app.
• The SDK does not call AI models. Your app calls them with the model maker's own SDK through Playcode: see Add AI to your app.
• Image generation from your app's own key is not available yet: the key cannot carry the image permission today.
• An operation added to the API after the SDK's release needs a newer SDK.