@synopackageland/app 0.0.0-stage → 0.10.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 synopkgland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,220 @@
-# Temporary Holding Version
+# @synopackageland/app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Node SDK for the backend of a Synology Package Land App written in
+TypeScript or JavaScript. Node 18 or later (DSM Package Center's
+`Node.js_v18`, `Node.js_v20`, `Node.js_v22`), ESM only, no runtime
+dependencies.
+
+The package's CGI is the synopkgland Go runtime (`bridge/cmd/runtime`). It
+checks the request's origin, the DSM session, the entry gate, the method's
+policy in `permissions.json` and the deadline, and only then starts the App,
+as the package account, and hands it the call over the bridge channel
+([`spec/bridge/v1`](../spec/bridge/v1/README.md)): JSON frames on stdin and
+stdout, one process per call. The App never runs as root and never sees the
+DSM session; what needs the session it asks of the runtime with
+`ctx.runtime`.
+
+## An App
+
+```ts
+import fs from 'node:fs'
+import path from 'node:path'
+import { App, AppError } from '@synopackageland/app'
+
+const app = new App()
+
+app.method('hello.greet', (ctx) => ({ message: `Hello, ${ctx.user}` }))
+
+app.method('hello.save', (ctx, params: { note?: unknown } | null) => {
+  if (typeof params?.note !== 'string') throw new AppError('bad_request', 'note must be a string')
+  const notes = path.join(process.env.SYNOPKGLAND_DATA_DIR!, 'notes')
+  fs.mkdirSync(notes, { recursive: true, mode: 0o700 })
+  fs.writeFileSync(path.join(notes, `${ctx.requestId}.txt`), params.note, { flag: 'wx' })
+  return { bytes: Buffer.byteLength(params.note) }
+})
+
+await app.run()
+```
+
+The browser calls it with `@synopackageland/sdk` as any other method:
+`{"method":"hello.greet"}` answers `{"success":true,"data":{"message":"Hello, alice"}}`.
+
+The methods must be the ones in the package's `bridge.json` (`methods`);
+the runtime registers its routes from there, and an App that says hello with
+other methods is refused. Their policy is in `permissions.json`, as for a Go
+App.
+
+## API
+
+### `new App(options?)`
+
+- `options.log(error)`: where an unexpected error goes. The default writes it
+  to stderr, which DSM keeps in the package's log. The browser only sees
+  `internal`.
+
+### `app.method(name, handler)`
+
+Registers a method and returns the App. `name` is `<group>.<name>` in lower
+case (`^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$`); a name registered twice
+throws.
+
+`handler(ctx, params)` returns the data, or a promise of it: any JSON value,
+`undefined` is `null`. `params` is the request's `params` as the browser sent
+it. The type parameter of `method<P>` only annotates it; check the value
+before you use it.
+
+### `app.run()`
+
+Answers the one call the runtime sends on stdin, then exits. It refuses to
+start as root (exit status 1) and when `SYNOPKGLAND_BRIDGE` is not `stdio`
+(exit status 2), so it only runs under the runtime. While it serves, what
+the App writes to `process.stdout`, `console.log` included, goes to stderr:
+stdout is the channel. A child process started with `stdio: 'inherit'`
+would still share it; give it `'ignore'` or pipes.
+
+`node <entry> --describe` prints one JSON line instead,
+`{"sdk":"node/…","versions":[1],"methods":[…]}`, so the package build can
+check the methods against `bridge.json` and `permissions.json`.
+`app.describe()` returns the same object.
+
+### `app.serve(input, output)`
+
+Answers one call on any pair of streams and resolves once the result is
+written. `run` uses it on stdin and stdout; tests use it on a
+`PassThrough` pair, playing the runtime's side of the channel.
+
+### `Context`
+
+| Member | |
+|---|---|
+| `user` | The DSM user who called; empty for a public method |
+| `admin` | Whether the user is a DSM administrator |
+| `locale` | The first `Accept-Language` tag, or empty |
+| `requestId` | The request's ID, 32 hex digits, also in the runtime's log |
+| `deadline` | When the runtime ends the request, in `Date.now()` milliseconds |
+| `deadlineMs` | The time that was left when the runtime sent the call, in milliseconds |
+| `signal` | An `AbortSignal` aborted when the request is over; `signal.reason` is `'deadline'` or `'canceled'` |
+| `cancelled` | Whether `signal` is aborted |
+| `runtime(op, params?)` | Asks the runtime for a service on behalf of the caller; resolves to its result |
+
+All of it comes from the runtime's verified caller. A `Context` belongs to
+one call.
+
+### Errors
+
+`throw new AppError(code, message)` answers the browser
+`{"success":false,"error":{"code":…,"message":…}}`. `code` is either
+
+- the App's own code, `^[a-z][a-z0-9_]{0,63}$`, except the runtime's
+  reserved ones (`session_required`, `admin_required`,
+  `app_privilege_denied`, `auth_unavailable`, `unknown_method`,
+  `cross_origin`, `origin_required`, `request_timeout`, `request_canceled`,
+  `request_too_large`, `json_required`, `method_not_allowed`,
+  `app_unavailable`), or
+- an upper-case refusal of
+  [`spec/protocol/v1/errors.json`](../spec/protocol/v1/errors.json), such as
+  `SCOPE_DENIED`, which `@synopackageland/sdk` translates.
+
+Any other code throws `TypeError`, which, like any other error, answers the
+browser `internal` and writes why to stderr. `message` is cut to 1024 bytes
+of UTF-8. `AppError.badRequest(message)` is `new AppError('bad_request', message)`.
+
+Anything else a handler throws, data JSON cannot encode (a `BigInt`, a
+cycle), answers `internal`; the error goes to `log`, never to the browser.
+
+### Services
+
+`ctx.runtime(op, params)` sends the runtime a service request and resolves to
+its result, or `null` when it has none. When the runtime refuses it rejects
+with `ServiceError` (`op`, `code`, `message`): `unknown_service` for an op
+the runtime does not offer, otherwise the service's code. A `ServiceError` a
+handler does not catch reaches the browser when its code is a protocol v1
+refusal, and is `internal` otherwise. An `op` that is not a service name, or
+`params` JSON cannot encode, rejects with `TypeError` before anything is
+sent.
+
+The runtime offers the services of the capabilities in `bridge.json`
+(`files.*`, `portal.status`, `delegate.*`, `bg.*`, `root.*`), listed with
+their params in [`spec/bridge/v1`](../spec/bridge/v1/README.md#services).
+They act for the verified caller, with the request's DSM session where they
+need one, and end with the call.
+
+```ts
+app.method('notes.list', (ctx) => ctx.runtime('files.list', { path: '/home/notes' }))
+```
+
+### Transfers
+
+A method `transfers` names in `bridge.json` is an HTTP upload or download.
+Its `params` is `{query, upload: {path, size}}` for an upload, a spool file
+to read, and `{query, download: {path}}` for a download, a spool file to
+write before answering `{name, content_type?}`
+([`spec/bridge/v1`](../spec/bridge/v1/README.md#transfers)).
+
+### Deadline and cancel
+
+The runtime owns the deadline. When it passes, or the browser goes away, the
+runtime sends `cancel` and `ctx.signal` aborts; one second later it kills the
+App's process group. Pass `ctx.signal` to `fetch`, `fs` and timers so that
+they stop with the request:
+
+```ts
+app.method('feed.fetch', async (ctx) => {
+  const reply = await fetch('https://example.com/feed.json', { signal: ctx.signal })
+  return reply.json()
+})
+```
+
+Once `signal` aborts, pending `ctx.runtime` calls, and later ones without
+asking, reject with `ServiceError` code `request_canceled`. If the channel
+ends early, `signal` aborts with `'canceled'`.
+
+### Numbers
+
+An App gets values, not JSON literals: `2.50` arrives as `2.5`, and integers
+above 2^53 lose precision. Carry 64-bit IDs and sizes as strings.
+
+## Testing an App
+
+`serve` takes any streams, so a test can play the runtime:
+
+```ts
+import { PassThrough } from 'node:stream'
+import { createInterface } from 'node:readline'
+
+const toApp = new PassThrough(), fromApp = new PassThrough()
+const lines = createInterface({ input: fromApp })[Symbol.asyncIterator]()
+const next = async () => JSON.parse((await lines.next()).value)
+app.serve(toApp, fromApp)
+toApp.write(JSON.stringify({ t: 'hello', versions: [1] }) + '\n')
+await next() // {t: 'hello', version: 1, sdk: 'node/…', methods: [...]}
+toApp.write(JSON.stringify({ t: 'call', id: '1', method: 'hello.greet', params: null,
+  ctx: { user: 'alice', admin: false, locale: 'en', request_id: '0'.repeat(32), deadline_ms: 60000 } }) + '\n')
+await next() // {t: 'result', id: '1', ok: true, data: {message: 'Hello, alice'}}
+```
+
+## In a package
+
+The App directory of the SPK is `/var/packages/<package>/target/app`. The
+runtime starts `<entry>` there with
+`/var/packages/<node.package>/target/usr/local/bin/node`, so the SPK depends
+on that Package Center package (`install_dep_packages`). The SDK has no
+dependencies: the package build copies `package.json` and `dist/` to
+`app/node_modules/@synopackageland/app/`, or bundles the App and the SDK
+into one file.
+
+## Development
+
+```sh
+npm ci
+npm run generate   # src/frames.ts and src/refusals.ts from spec/
+npm test           # type-checks src and test, then node:test
+npm run build      # dist/: ESM and .d.ts
+```
+
+`src/frames.ts` (json-schema-to-typescript, from
+`spec/bridge/v1/frames.schema.json`) and `src/refusals.ts` (from
+`spec/protocol/v1/errors.json`) are generated and committed; a test fails
+when they differ from `spec/`. `scripts/gate.sh` also runs the tests, the
+bridge's golden runner and the hello example on Node 18 in Docker
+(`scripts/node18-test.sh`).

package/dist/app.d.ts

@@ -0,0 +1,45 @@
+import { Writable, type Readable } from 'node:stream';
+import { type Context } from './context.js';
+/** The channel protocol version this SDK speaks. */
+export declare const VERSION = 1;
+/** The SDK's name in hello: node/<package version>. */
+export declare const SDK = "node/0.10.1";
+/**
+ * A method's implementation. params is the request's params as the browser
+ * sent them, not checked against P. The result is the data the browser gets,
+ * any JSON value; undefined is null.
+ */
+export type Handler<P = unknown> = (ctx: Context, params: P) => unknown;
+export interface AppOptions {
+    /**
+     * Where an unexpected error goes (stderr, the DSM log, by default); the
+     * browser only sees internal.
+     */
+    log?: (error: unknown) => void;
+}
+/** The App: its methods, served on one channel per call. */
+export declare class App {
+    #private;
+    constructor(options?: AppOptions);
+    /** Registers a method; its name must be in the package's bridge.json. */
+    method<P = unknown>(name: string, handler: Handler<P>): this;
+    /**
+     * Answers the one call on a channel; resolves once the result is written,
+     * or the channel ended without a call.
+     */
+    serve(input: Readable, output: Writable): Promise<void>;
+    /** What --describe prints: the App's methods, for the package build. */
+    describe(): {
+        sdk: string;
+        versions: number[];
+        methods: string[];
+    };
+    /**
+     * Answers the one call the runtime sends on stdin and exits. Refuses to
+     * start as root (exit status 1) or outside the runtime, when
+     * SYNOPKGLAND_BRIDGE is not stdio (exit status 2). With --describe it
+     * prints describe() as one JSON line instead. While it serves, what the App
+     * writes to process.stdout (console.log) goes to stderr.
+     */
+    run(): Promise<void>;
+}

package/dist/app.js

@@ -0,0 +1,121 @@
+import { Writable } from 'node:stream';
+import { Channel } from './channel.js';
+import { Call } from './context.js';
+import { browserError } from './errors.js';
+/** The channel protocol version this SDK speaks. */
+export const VERSION = 1;
+/** The SDK's name in hello: node/<package version>. */
+export const SDK = 'node/0.10.1';
+const methodName = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/;
+const internal = { code: 'internal', message: 'internal error' };
+/** The App: its methods, served on one channel per call. */
+export class App {
+    #methods = new Map();
+    #log;
+    constructor(options = {}) {
+        this.#log = options.log ?? ((error) => console.error(error));
+    }
+    /** Registers a method; its name must be in the package's bridge.json. */
+    method(name, handler) {
+        if (!methodName.test(name))
+            throw new TypeError(`invalid method name: ${name}`);
+        if (this.#methods.has(name))
+            throw new Error(`method registered twice: ${name}`);
+        this.#methods.set(name, handler);
+        return this;
+    }
+    /**
+     * Answers the one call on a channel; resolves once the result is written,
+     * or the channel ended without a call.
+     */
+    async serve(input, output) {
+        const channel = new Channel(input, output);
+        const hello = await channel.recv();
+        if (hello?.t !== 'hello' || !Array.isArray(hello.versions) || !hello.versions.includes(VERSION))
+            return;
+        await channel.send({ t: 'hello', version: VERSION, sdk: SDK, methods: this.describe().methods });
+        const call = await channel.recv();
+        if (call?.t !== 'call')
+            return;
+        const id = call.id;
+        const state = new Call(channel, call.ctx);
+        void follow(channel, id, state);
+        const result = await this.#answer(id, call, state.ctx);
+        state.close();
+        await channel.write(result);
+    }
+    /** What --describe prints: the App's methods, for the package build. */
+    describe() {
+        return { sdk: SDK, versions: [VERSION], methods: [...this.#methods.keys()].sort() };
+    }
+    /**
+     * Answers the one call the runtime sends on stdin and exits. Refuses to
+     * start as root (exit status 1) or outside the runtime, when
+     * SYNOPKGLAND_BRIDGE is not stdio (exit status 2). With --describe it
+     * prints describe() as one JSON line instead. While it serves, what the App
+     * writes to process.stdout (console.log) goes to stderr.
+     */
+    async run() {
+        if (process.argv.length === 3 && process.argv[2] === '--describe') {
+            process.stdout.write(JSON.stringify(this.describe()) + '\n');
+            return;
+        }
+        const refusal = refuse();
+        if (refusal) {
+            process.stderr.write(`@synopackageland/app: ${refusal.message}\n`);
+            process.exitCode = refusal.status;
+            return;
+        }
+        await this.serve(process.stdin, takeStdout());
+        // The result is written; stdin and whatever the handler left behind
+        // would keep the process alive.
+        process.exit(0);
+    }
+    // The encoded result frame. Data that JSON cannot encode fails here, before
+    // anything is written.
+    async #answer(id, call, ctx) {
+        const encode = (frame) => JSON.stringify(frame);
+        try {
+            const handler = this.#methods.get(call.method);
+            if (!handler)
+                throw new Error(`the runtime called ${String(call.method)}, which the App does not have`);
+            const data = await handler(ctx, call.params);
+            return encode({ t: 'result', id, ok: true, data: data === undefined ? null : data });
+        }
+        catch (e) {
+            const error = browserError(e);
+            if (error)
+                return encode({ t: 'result', id, ok: false, error });
+            this.#log(e);
+            return encode({ t: 'result', id, ok: false, error: internal });
+        }
+    }
+}
+function refuse() {
+    if (process.geteuid?.() === 0)
+        return { message: 'refusing to run as root', status: 1 };
+    if (process.env.SYNOPKGLAND_BRIDGE !== 'stdio') {
+        return { message: 'the runtime starts an App with SYNOPKGLAND_BRIDGE=stdio; run --describe to list its methods', status: 2 };
+    }
+    return undefined;
+}
+// The channel's end of stdout. process.stdout itself, and so console.log,
+// writes to stderr from now on: a stray line must not break the channel.
+function takeStdout() {
+    const stdout = process.stdout;
+    const write = stdout.write.bind(stdout);
+    stdout.write = process.stderr.write.bind(process.stderr);
+    // A runtime that went away is seen as the end of the channel, not a crash.
+    stdout.on('error', () => { });
+    return new Writable({ write: (chunk, encoding, done) => write(chunk, encoding, done) });
+}
+// Reads the frames that arrive while the handler runs.
+async function follow(channel, id, call) {
+    for (let f = await channel.recv(); f; f = await channel.recv()) {
+        if (f.t === 'svc_result')
+            call.answer(f);
+        else if (f.t === 'cancel' && f.id === id && (f.reason === 'deadline' || f.reason === 'canceled'))
+            call.cancel(f.reason);
+    }
+    call.close();
+}

package/dist/channel.d.ts

@@ -0,0 +1,13 @@
+import type { Readable, Writable } from 'node:stream';
+import type { Frame } from './frames.js';
+export type Received = {
+    t: string;
+    [member: string]: unknown;
+};
+export declare class Channel {
+    #private;
+    constructor(input: Readable, output: Writable);
+    recv(): Promise<Received | null>;
+    send(frame: Frame): Promise<void>;
+    write(line: string): Promise<void>;
+}

package/dist/channel.js

@@ -0,0 +1,37 @@
+import { createInterface } from 'node:readline';
+// One channel to the runtime: a frame is one line of JSON (spec/bridge/v1
+// README, Transport).
+export class Channel {
+    #lines;
+    #output;
+    constructor(input, output) {
+        this.#lines = createInterface({ input, crlfDelay: Infinity })[Symbol.asyncIterator]();
+        this.#output = output;
+        // A runtime that went away is seen as the end of the channel, not a crash.
+        output.on('error', () => { });
+    }
+    // The next frame, or null once the channel ended or broke.
+    async recv() {
+        try {
+            const { value, done } = await this.#lines.next();
+            if (done)
+                return null;
+            const frame = JSON.parse(value);
+            return isReceived(frame) ? frame : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    send(frame) {
+        return this.write(JSON.stringify(frame));
+    }
+    // Writes an encoded frame; resolves once it is handed to the system, so
+    // that exiting after it does not drop it.
+    write(line) {
+        return new Promise((resolve) => this.#output.write(line + '\n', () => resolve()));
+    }
+}
+function isReceived(frame) {
+    return typeof frame === 'object' && frame !== null && typeof frame.t === 'string';
+}

package/dist/context.d.ts

@@ -0,0 +1,48 @@
+import type { Channel, Received } from './channel.js';
+import type { CallContext } from './frames.js';
+/**
+ * Why the request is over: its deadline passed, or the browser went away
+ * (or the runtime closed the channel).
+ */
+export type CancelReason = 'deadline' | 'canceled';
+/**
+ * What the runtime verified about the call, and the way back to it. A
+ * Context belongs to one call; do not keep it after the handler returns.
+ */
+export interface Context {
+    /** The DSM user who called; empty for a public method. */
+    readonly user: string;
+    /** Whether the user is a DSM administrator. */
+    readonly admin: boolean;
+    /** The first Accept-Language tag of the request, or empty. */
+    readonly locale: string;
+    /** The request's ID, 32 hex digits, also in the runtime's log. */
+    readonly requestId: string;
+    /** When the runtime ends the request, in Date.now() milliseconds. */
+    readonly deadline: number;
+    /** The time that was left when the runtime sent the call, in milliseconds. */
+    readonly deadlineMs: number;
+    /**
+     * Aborted when the request is over; its reason is a CancelReason. Pass it
+     * to fetch, fs and timers to stop with the request.
+     */
+    readonly signal: AbortSignal;
+    /** Whether signal is aborted. */
+    readonly cancelled: boolean;
+    /**
+     * Asks the runtime for a service on behalf of the caller and resolves to
+     * its result (null when it has none). Rejects with ServiceError when the
+     * runtime refuses, with ServiceError request_canceled once the request is
+     * over (pending calls too), and with TypeError for an op that is not a service name
+     * or params JSON cannot encode.
+     */
+    runtime(op: string, params?: unknown): Promise<unknown>;
+}
+export declare class Call {
+    #private;
+    readonly ctx: Context;
+    constructor(channel: Channel, c: CallContext);
+    answer(frame: Received): void;
+    cancel(reason: CancelReason): void;
+    close(): void;
+}

package/dist/context.js

@@ -0,0 +1,65 @@
+import { ServiceError } from './errors.js';
+const opName = /^[a-z][a-z0-9_]*(\.[a-z][a-zA-Z0-9_]*)+$/;
+// One call on its channel: the handler's Context and the services it waits for.
+export class Call {
+    ctx;
+    #channel;
+    #abort = new AbortController();
+    #pending = new Map();
+    #next = 0;
+    constructor(channel, c) {
+        this.#channel = channel;
+        const signal = this.#abort.signal;
+        this.ctx = {
+            user: c.user,
+            admin: c.admin,
+            locale: c.locale,
+            requestId: c.request_id,
+            deadline: Date.now() + c.deadline_ms,
+            deadlineMs: c.deadline_ms,
+            signal,
+            get cancelled() {
+                return signal.aborted;
+            },
+            runtime: (op, params) => this.#runtime(op, params),
+        };
+    }
+    #runtime(op, params = null) {
+        if (!opName.test(op))
+            return Promise.reject(new TypeError(`invalid service name: ${op}`));
+        if (this.#abort.signal.aborted)
+            return Promise.reject(closed(op));
+        const id = `s${++this.#next}`;
+        return new Promise((resolve, reject) => {
+            // send throws for params JSON cannot encode; the answer comes later.
+            void this.#channel.send({ t: 'svc', id, op, params });
+            this.#pending.set(id, { op, resolve, reject });
+        });
+    }
+    // Settles the service a svc_result answers.
+    answer(frame) {
+        const pending = this.#pending.get(frame.id);
+        if (!pending)
+            return;
+        this.#pending.delete(frame.id);
+        const error = frame.error;
+        if (frame.ok === true)
+            pending.resolve(frame.result ?? null);
+        else
+            pending.reject(new ServiceError(pending.op, error?.code ?? 'internal', error?.message ?? 'malformed service reply'));
+    }
+    // The request is over: what is pending ends, and nothing more is asked.
+    cancel(reason) {
+        this.#abort.abort(reason);
+        for (const p of this.#pending.values())
+            p.reject(closed(p.op));
+        this.#pending.clear();
+    }
+    // The channel ended, or the result is written; a first reason stays.
+    close() {
+        this.cancel('canceled');
+    }
+}
+function closed(op) {
+    return new ServiceError(op, 'request_canceled', 'the runtime closed the channel');
+}

package/dist/errors.d.ts

@@ -0,0 +1,31 @@
+export declare const reservedCodes: ReadonlySet<string>;
+export declare function isAppCode(code: string): boolean;
+/**
+ * An error the browser sees as {code, message}. code is the App's own code
+ * (^[a-z][a-z0-9_]{0,63}$, except the runtime's) or an upper-case refusal of
+ * spec/protocol/v1/errors.json, which @synopackageland/sdk translates; any
+ * other code throws TypeError. message is cut to 1024 bytes of UTF-8.
+ */
+export declare class AppError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+    /** AppError('bad_request', message). */
+    static badRequest(message: string): AppError;
+}
+/**
+ * A service the App asked for with ctx.runtime was refused. code is the
+ * runtime's: an api code such as unknown_service, or for executor-backed
+ * services a code of spec/protocol/v1/errors.json. Uncaught, an upper-case
+ * protocol v1 refusal reaches the browser as an AppError would; any other
+ * code is internal.
+ */
+export declare class ServiceError extends Error {
+    readonly code: string;
+    /** The service: the op given to ctx.runtime. */
+    readonly op: string;
+    constructor(op: string, code: string, message: string);
+}
+export declare function browserError(e: unknown): {
+    code: string;
+    message: string;
+} | undefined;

package/dist/errors.js

@@ -0,0 +1,77 @@
+import { protocolRefusals } from './refusals.js';
+// The runtime's own refusals (spec/bridge/v1 README, Errors). An App that
+// returned one would make the browser act on a decision the runtime did not
+// take, such as signing in again.
+export const reservedCodes = new Set([
+    'session_required', 'admin_required', 'app_privilege_denied', 'auth_unavailable',
+    'unknown_method', 'cross_origin', 'origin_required', 'request_timeout',
+    'request_canceled', 'request_too_large', 'json_required', 'method_not_allowed',
+    'app_unavailable',
+]);
+const appCode = /^[a-z][a-z0-9_]{0,63}$/;
+const maxMessageBytes = 1024;
+// isAppCode reports whether an App may return code: its own lower-case code,
+// or a protocol v1 refusal it got from a service and passes on.
+export function isAppCode(code) {
+    return (appCode.test(code) && !reservedCodes.has(code)) || protocolRefusals.has(code);
+}
+/**
+ * An error the browser sees as {code, message}. code is the App's own code
+ * (^[a-z][a-z0-9_]{0,63}$, except the runtime's) or an upper-case refusal of
+ * spec/protocol/v1/errors.json, which @synopackageland/sdk translates; any
+ * other code throws TypeError. message is cut to 1024 bytes of UTF-8.
+ */
+export class AppError extends Error {
+    code;
+    constructor(code, message) {
+        if (!isAppCode(code))
+            throw new TypeError(`an App may not return error code ${JSON.stringify(code)}`);
+        super(truncate(message));
+        this.name = 'AppError';
+        this.code = code;
+    }
+    /** AppError('bad_request', message). */
+    static badRequest(message) {
+        return new AppError('bad_request', message);
+    }
+}
+function truncate(message) {
+    if (Buffer.byteLength(message) <= maxMessageBytes)
+        return message;
+    let bytes = 0;
+    let end = 0;
+    for (const char of message) {
+        bytes += Buffer.byteLength(char);
+        if (bytes > maxMessageBytes)
+            break;
+        end += char.length;
+    }
+    return message.slice(0, end);
+}
+/**
+ * A service the App asked for with ctx.runtime was refused. code is the
+ * runtime's: an api code such as unknown_service, or for executor-backed
+ * services a code of spec/protocol/v1/errors.json. Uncaught, an upper-case
+ * protocol v1 refusal reaches the browser as an AppError would; any other
+ * code is internal.
+ */
+export class ServiceError extends Error {
+    code;
+    /** The service: the op given to ctx.runtime. */
+    op;
+    constructor(op, code, message) {
+        super(message);
+        this.name = 'ServiceError';
+        this.code = code;
+        this.op = op;
+    }
+}
+// The error the browser gets for an error the handler did not catch, or
+// undefined when it gets internal.
+export function browserError(e) {
+    if (e instanceof AppError)
+        return { code: e.code, message: e.message };
+    if (e instanceof ServiceError && protocolRefusals.has(e.code))
+        return { code: e.code, message: truncate(e.message) };
+    return undefined;
+}

package/dist/frames.d.ts

@@ -0,0 +1,63 @@
+export type Frame = RuntimeHello | AppHello | Call | Cancel | Svc | SvcResult | Result;
+export type Method = string;
+export type Id = string;
+export interface RuntimeHello {
+    t: "hello";
+    /**
+     * @minItems 1
+     */
+    versions: [number, ...number[]];
+}
+export interface AppHello {
+    t: "hello";
+    version: number;
+    sdk: string;
+    methods: Method[];
+}
+export interface Call {
+    t: "call";
+    id: Id;
+    method: Method;
+    params: unknown;
+    ctx: CallContext;
+}
+export interface CallContext {
+    user: string;
+    admin: boolean;
+    locale: string;
+    request_id: string;
+    deadline_ms: number;
+}
+export interface Cancel {
+    t: "cancel";
+    id: Id;
+    reason: "deadline" | "canceled";
+}
+export interface Svc {
+    t: "svc";
+    id: Id;
+    op: string;
+    params: unknown;
+}
+export interface SvcResult {
+    t: "svc_result";
+    id: Id;
+    ok: boolean;
+    result?: unknown;
+    error?: SvcError;
+}
+export interface SvcError {
+    code: string;
+    message: string;
+}
+export interface Result {
+    t: "result";
+    id?: Id;
+    ok: boolean;
+    data?: unknown;
+    error?: ResultError;
+}
+export interface ResultError {
+    code: string;
+    message: string;
+}

package/dist/frames.js

@@ -0,0 +1,2 @@
+// Code generated by scripts/generate.mjs from spec/bridge/v1/frames.schema.json. DO NOT EDIT.
+export {};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { App, SDK, VERSION, type AppOptions, type Handler } from './app.js';
+export type { CancelReason, Context } from './context.js';
+export { AppError, ServiceError } from './errors.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+// Node SDK for Synology Package Land Apps (channel spec/bridge/v1).
+//
+// The Go runtime checks the request's origin, the DSM session, the entry
+// gate, the route policy and the deadline; a handler here only sees calls
+// that passed them, and asks the runtime for services with ctx.runtime. No
+// dependencies; Node 18 or later.
+export { App, SDK, VERSION } from './app.js';
+export { AppError, ServiceError } from './errors.js';

package/dist/refusals.d.ts

@@ -0,0 +1 @@
+export declare const protocolRefusals: ReadonlySet<string>;

package/dist/refusals.js

@@ -0,0 +1,32 @@
+// Code generated by scripts/generate.mjs from spec/protocol/v1/errors.json. DO NOT EDIT.
+// The upper-case refusal codes of protocol v1. An App may return them, so the
+// browser's SDK can translate them.
+export const protocolRefusals = new Set([
+    'AUTH_DENIED',
+    'INELIGIBLE',
+    'APP_DENIED',
+    'ADMIN_REQUIRED',
+    'DELEGATION_DENIED',
+    'SCOPE_DENIED',
+    'POLICY_DENIED',
+    'PEER_DENIED',
+    'PERMISSION_DENIED',
+    'UNKNOWN_OP',
+    'INVALID_REQUEST',
+    'REQUEST_TOO_LARGE',
+    'EXECUTOR_PAUSED',
+    'STORAGE_ERROR',
+    'INTERNAL',
+    'WRITE_FAILED',
+    'READ_FAILED',
+    'DSM_FAILED',
+    'ROOT_FAILED',
+    'ROOT_TIMEOUT',
+    'ROOT_BUSY',
+    'ROOT_STAGING_FULL',
+    'ROOT_JOB_NOT_FOUND',
+    'PORTAL_FAILED',
+    'NO_SPACE',
+    'SCOPE_APPROVAL_STALE',
+    'IDENTITY_CHANGED',
+]);

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@synopackageland/app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.10.1",
+  "description": "Node SDK for Synology Package Land Apps: the backend methods behind the synopkgland Go runtime (channel spec/bridge/v1)",
+  "license": "MIT",
+  "homepage": "https://github.com/synopackageland/syno-pkg-land-sdk/tree/main/node#readme",
+  "bugs": {
+    "url": "https://github.com/synopackageland/syno-pkg-land-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/synopackageland/syno-pkg-land-sdk.git",
+    "directory": "node"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "prepack": "npm run build",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "generate": "node scripts/generate.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "rm -rf build && tsc && node --test --test-reporter=spec build/test/*.test.js"
+  },
+  "devDependencies": {
+    "@types/node": "18.19.130",
+    "json-schema-to-typescript": "16.0.0",
+    "typescript": "5.9.3"
+  }
+}