Examples & patterns
Working code for the things you'll do most often.
What you'll find
| Task | Sample |
|---|---|
| Authenticate and call the API | See Quick Start |
| Upload a file and reference it from a conversation | github.com/algoshred/burdenoff-examples/tree/main/file-upload |
| Subscribe to live message updates | github.com/algoshred/burdenoff-examples/tree/main/subscriptions |
| Register an OAuth app and do delegation | github.com/algoshred/burdenoff-examples/tree/main/oauth-delegation |
| Write a webhook receiver | github.com/algoshred/burdenoff-examples/tree/main/webhooks |
| Build a UI plugin | github.com/algoshred/burdenoff-examples/tree/main/ui-plugin |
| Build an AI plugin | github.com/algoshred/burdenoff-examples/tree/main/ai-plugin |
| Author a workflow | github.com/algoshred/burdenoff-examples/tree/main/workflow |
| Send notifications via Slack provider | github.com/algoshred/burdenoff-examples/tree/main/notification-provider |
Patterns
Idempotent event consumer
Always include an idempotency key (the event ID is fine) and short-circuit if you've already processed it:
sdk.events.consume('file.uploaded', 'thumbnail-svc', async (event) => {
const seen = await redis.get(`processed:${event.id}`);
if (seen) return;
await generateThumbnail(event.fileId);
await redis.setex(`processed:${event.id}`, 86400, '1');
});
Workspace-scoped resolver
Always read x-workspace-id from headers and filter by it:
const conversations = (parent, args, ctx) =>
prisma.conversation.findMany({ where: { workspaceId: ctx.workspaceId } });
Delegation-aware action
If the request has x-consent-granted-by, audit-log both the app and the user:
auditLog.write({
actorId: ctx.actorId,
actorType: ctx.actorType,
onBehalfOf: ctx.consentGrantedBy ?? null,
action: 'file.delete',
resource: fileId,
});