TypeScript SDK Beta

A typed client for the Device SDK API, with show, ask and notify helpers

Beta. The Device SDK is live for design partners: Dopl issues your project's keys while the developer portal is being built, and @dopl/sdk is available on request. Agents that act for one signed in Dopl user can use the hosted MCP server instead.

@dopl/sdk is a typed client for every route in the API reference, with request and response types taken from the same contract. It runs on Node 18.17 or later and anywhere with a global fetch.

Access

The package is private while the Device SDK is in testing and is not on npm. It is available to design partners on request from sales@usedopl.com, and the Quickstart walks through it end to end.

Create a client

import { Dopl } from "@dopl/sdk";

const dopl = new Dopl({ apiKey: process.env.DOPL_SECRET_KEY! });

new Dopl({ apiKey, baseUrl, fetch, headers }) takes a secret key, or a publishable pk_ key that can only call connectSessions.create; the client refuses every other call with a pk_ key before sending anything. The key is never logged or kept as a property on the client.

Methods

MethodRoute
connectSessions.create(body)POST /connect_sessions
connections.exchange({ public_token })POST /connections/exchange
connections.list(externalUserId)GET /users/{external_user_id}/connections
connections.revoke(connectionId)DELETE /connections/{id}
users.context(externalUserId)GET /users/{external_user_id}/context
users.deliver(externalUserId, body)POST /users/{external_user_id}/deliver
devices.action(deviceId, capability, args)POST /devices/{device_id}/actions/{capability}
devices.get(deviceId)GET /devices/{id}
actions.get(actionId)GET /actions/{id}
events.list({ cursor, limit, ...filters })GET /events
webhookEndpoints.create({ url, enabled_events })POST /webhook_endpoints
webhookEndpoints.list({ cursor, limit })GET /webhook_endpoints
webhookEndpoints.get(endpointId)GET /webhook_endpoints/{id}
webhookEndpoints.update(endpointId, body)PATCH /webhook_endpoints/{id}
webhookEndpoints.delete(endpointId)DELETE /webhook_endpoints/{id}
webhookEndpoints.rotateSecret(endpointId, { overlap_seconds })POST /webhook_endpoints/{id}/rotate_secret
webhookEndpoints.listDeliveries(endpointId, { cursor, limit })GET /webhook_endpoints/{id}/deliveries
webhookDeliveries.get(deliveryId)GET /webhook_deliveries/{id}
webhookDeliveries.replay(deliveryId)POST /webhook_deliveries/{id}/replay
show(externalUserId, { text, blocks })Deliver with the display intent
notify(externalUserId, { text })Deliver with the notify intent
ask(externalUserId, { question, options })Deliver with the ask intent, then poll the action for the answer

show, notify and ask are methods, not routes, so the API keeps one way to deliver. Each takes the Deliver options too: urgency, target, profile and idempotencyKey.

Asking

const answer = await dopl.ask("usr_123", { question: "Ship it?", options: ["Yes", "No"], timeoutMs: 60_000 });

if (answer.status === "answered") console.log(answer.answer);

ask delivers the question, then polls actions.get with the delivery_id every second until the action is done or fails, or until timeoutMs passes, 200 seconds by default. An answer resolves with status: "answered", a timeout resolves with status: "timeout", and a failed action throws.

Idempotency

Every POST takes { idempotencyKey }, which the SDK sends as the Idempotency-Key header and in the body. When you pass none it creates a fresh key per call, so pass your own to make a retry safe: the same key returns the first result instead of acting twice.

Errors

Every failure throws a DoplError with the fields of the error shape (code, type, message, retryable, docUrl, deviceKind) plus the HTTP status and the requestId from the Request-Id header. When no error body came back, code is one the SDK sets itself: network_error, unexpected_response or publishable_key_not_allowed.

import { DoplError } from "@dopl/sdk";

try {
  await dopl.notify("usr_123", { text: "Build done" });
} catch (err) {
  if (err instanceof DoplError && err.retryable) {
    // retry later with the same idempotencyKey
  }
}

A Python SDK is planned after TypeScript.