SDK guide
@lelap/sdk has the protocol’s types and zod schemas, and createAddon, which turns a few handlers into a standard fetch(request) function with routing, CORS, caching headers and JSON errors done for you.
Install
The SDK is MIT-licensed, so you can use it in an add-on under any license. It needs a runtime with the Fetch API (Request and Response).
npm install @lelap/sdk hono
npm install --save-dev wranglerOr start from services/template, the smallest working add-on with the SDK wired in. The SDK’s source is in packages/sdk.
A complete add-on
One catalog, meta and streams, served with Hono on Cloudflare Workers. Every handler may be async.
import { AddonError, createAddon, type Manifest, type MetaPreview } from '@lelap/sdk';
import { Hono } from 'hono';
const manifest: Manifest = {
id: 'com.example.readings',
version: '1.0.0',
protocol: 1,
name: 'Example Readings',
description: 'Public-domain books read by volunteers.',
types: ['audiobook'],
resources: ['catalog', 'meta', 'stream'],
idPrefixes: ['example:'],
catalogs: [{ type: 'audiobook', id: 'new', name: 'New releases', extra: [{ name: 'skip' }] }],
};
// Your own data source: a database, a feed, an API you're allowed to use.
const books: MetaPreview[] = [
{
id: 'example:secret-garden',
type: 'audiobook',
name: 'The Secret Garden',
author: 'Frances Hodgson Burnett',
cover: 'https://media.example.com/secret-garden/cover.jpg',
},
];
const PAGE = 50;
const addon = createAddon({
manifest,
catalog: ({ extra }) => {
const skip = Number(extra.skip ?? 0);
if (!Number.isInteger(skip) || skip < 0) throw new AddonError(400, 'skip must be a whole number');
return { metas: books.slice(skip, skip + PAGE), cacheMaxAge: 6 * 3600 };
},
meta: ({ id }) => {
const book = books.find((b) => b.id === id);
if (!book) return null; // becomes a 404
return {
meta: { ...book, chapters: [{ title: 'There Is No One Left', startMs: 0 }] },
cacheMaxAge: 86400,
};
},
stream: ({ id }) => {
if (id !== 'example:secret-garden') return { streams: [] };
return {
streams: [
{
sourceKey: 'secret-garden-ana',
name: 'Example Readings',
title: 'Read by Ana Reader',
parts: [
{ url: 'https://media.example.com/secret-garden/01.mp3', durationMs: 1123000 },
{ url: 'https://media.example.com/secret-garden/02.mp3', durationMs: 1342000 },
],
},
],
cacheMaxAge: 86400,
};
},
});
const app = new Hono();
app.get('/', (c) => c.redirect('/manifest.json'));
app.all('*', (c) => addon.fetch(c.req.raw));
export default app;name = "example-readings"
main = "src/index.ts"
compatibility_date = "2026-11-01"npx wrangler dev # http://localhost:8787/manifest.json
npx wrangler deployHandlers get:
catalog({ type, id, extra, request }):extrais an object of strings, such as{ search: "dune", skip: "20" }. Return{ metas, cacheMaxAge? }.meta({ type, id, request }): return{ meta, cacheMaxAge? }, ornullfor an unknown ID.stream({ type, id, request }): return{ streams, cacheMaxAge? }; an empty list when you have nothing.
IDs and extras arrive decoded. Leave out the handlers you don’t need and the resources you don’t declare; their routes answer 404. The protocol reference has every field.
Deno, Bun and Node
addon.fetch is a plain (request: Request) => Promise<Response>, so it runs without Hono too. Workers also take export default { fetch: addon.fetch }.
// main.ts: deno run --allow-net main.ts
Deno.serve(addon.fetch);// index.ts: bun run index.ts
export default { fetch: addon.fetch };// Node, with @hono/node-server
import { serve } from '@hono/node-server';
serve({ fetch: addon.fetch, port: 8787 });Options
createAddon(handlers, options) takes:
basePath: the path the add-on is mounted under, such as/librivox. Defaults to the root. Requests outside it answer404.validate: check handler output against the protocol schemas. On by default.onError(error, request): called with anything a handler throws, other than anAddonError, before the500goes out. Use it for logging.
Several add-ons, each with its own manifest, can share one Worker:
const librivox = createAddon(librivoxHandlers, { basePath: '/librivox' });
const catalog = createAddon(catalogHandlers);
const app = new Hono();
app.all('/librivox/*', (c) => librivox.fetch(c.req.raw));
app.all('*', (c) => catalog.fetch(c.req.raw));const addon = createAddon(handlers, {
onError: (error, request) => console.error(request.url, error),
});Errors
Throw new AddonError(status, message) to answer with that status and { "error": message }. Anything else a handler throws becomes a 500with { "error": "The add-on failed to answer" }, so internal details never reach listeners.
import { AddonError } from '@lelap/sdk';
catalog: async ({ extra }) => {
if (!extra.search?.trim()) throw new AddonError(400, 'Type something to search for');
const response = await fetch(upstreamSearchUrl(extra.search));
if (response.status === 429) throw new AddonError(503, 'The source is busy, try again soon');
// …
},The SDK answers these on its own, always as JSON with CORS headers:
204forOPTIONSpreflights.405for methods other thanGET,HEADandOPTIONS.404for unknown paths, resources or types the manifest doesn’t declare, catalogs it doesn’t list, missing handlers andmetareturningnull.
The SDK doesn’t check idPrefixes on incoming requests; the app only sends IDs you declared, but answer unknown IDs with null or an empty list anyway.
Validation
createAddonchecks the manifest when it’s called and throws if it doesn’t match the protocol, so a broken manifest fails at startup, not in the app.- With
validateon, every catalog, meta and stream response is checked before it’s sent. Output that doesn’t match is a500, andonErrorgets the zod message naming the field. Fields the protocol doesn’t have are dropped. - With
validate: false, handler output is sent as it is. Turn it off only once your tests cover every handler.
The schemas are exported too (Manifest, CatalogResponse, MetaResponse, StreamResponse and the objects inside them), and so are their types under the same names.
Testing
addon.fetch needs no server: build a Request, await the Response. Keep createAddon in a module of its own, such as src/addon.ts, and import it from the Worker entry and from the tests. Remember that IDs in paths are percent-encoded. The SDK also exports catalogPath, metaPath and streamPath, which build paths the way the app does.
import { CatalogResponse } from '@lelap/sdk';
import { expect, test } from 'vitest';
import { addon } from './addon';
test('the catalog pages with skip', async () => {
const response = await addon.fetch(
new Request('https://addon.test/catalog/audiobook/new/skip=50.json'),
);
expect(response.status).toBe(200);
expect(response.headers.get('Access-Control-Allow-Origin')).toBe('*');
const body = CatalogResponse.parse(await response.json());
expect(body.metas).toHaveLength(0);
});
test('unknown IDs are a 404', async () => {
const response = await addon.fetch(
new Request('https://addon.test/meta/audiobook/example%3Anope.json'),
);
expect(response.status).toBe(404);
});Add it to the app
- Deploy the add-on, or run it on a machine your phone can reach.
- In Lelap, open Settings → Add-ons, paste the manifest URL, such as
https://addon.example.com/manifest.json, and add it. - Its catalogs show up on Home and in Discover, and searchable catalogs in Search. Items whose ID prefix it declares get its meta and streams.
The web app needs HTTPS and the CORS headers the SDK sends. Keep your sourceKeyvalues stable across versions; listeners’ saved places depend on them.