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).

Terminal
npm install @lelap/sdk hono
npm install --save-dev wrangler

Or 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.

src/index.ts
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;
wrangler.toml
name = "example-readings"
main = "src/index.ts"
compatibility_date = "2026-11-01"
Terminal
npx wrangler dev      # http://localhost:8787/manifest.json
npx wrangler deploy

Handlers get:

  • catalog({ type, id, extra, request }): extra is an object of strings, such as { search: "dune", skip: "20" }. Return { metas, cacheMaxAge? }.
  • meta({ type, id, request }): return { meta, cacheMaxAge? }, or null for 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 }.

Deno
// main.ts: deno run --allow-net main.ts
Deno.serve(addon.fetch);
Bun
// index.ts: bun run index.ts
export default { fetch: addon.fetch };
Node
// 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 answer 404.
  • validate: check handler output against the protocol schemas. On by default.
  • onError(error, request): called with anything a handler throws, other than an AddonError, before the 500 goes 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:

  • 204 for OPTIONS preflights.
  • 405 for methods other than GET, HEAD and OPTIONS.
  • 404 for unknown paths, resources or types the manifest doesn’t declare, catalogs it doesn’t list, missing handlers and meta returning null.

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

  • createAddon checks 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 validate on, every catalog, meta and stream response is checked before it’s sent. Output that doesn’t match is a 500, and onError gets 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.

src/addon.test.ts
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

  1. Deploy the add-on, or run it on a machine your phone can reach.
  2. In Lelap, open Settings → Add-ons, paste the manifest URL, such as https://addon.example.com/manifest.json, and add it.
  3. 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.