@marcelsud/keel.ts 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcelo Santos
+
+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,110 @@
-# Temporary Holding Version
+# @marcelsud/keel.ts
 
-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.
+Use Keel from TypeScript to write services, call typed APIs, store data, publish events, and run background jobs.
+
+## Install
+
+Use Node.js 22+ or Bun 1.3+:
+
+```sh
+npm install @marcelsud/keel.ts
+```
+
+Or with Bun:
+
+```sh
+bun add @marcelsud/keel.ts
+```
+
+You need a running Keel environment. For the standalone storage example below, install the [Keel CLI](https://github.com/marcelsud/keel#install-the-cli) and run `keel` in another terminal first. To run a service with `keel dev`, configure its startup command in `keel.json`, for example `{ "command": ["bun", "run", "main.ts"] }`.
+
+## Connect and store data
+
+```ts
+import { createKeel } from "@marcelsud/keel.ts";
+
+const app = await createKeel({
+  name: "notes",
+  url: process.env.KEEL_URL,
+  token: process.env.KEEL_TOKEN,
+});
+
+try {
+  const id = await app.collection.insert("notes", { body: "Hello" });
+  console.log(await app.collection.get("notes", id));
+} finally {
+  await app.stop();
+}
+```
+
+## Call a typed service
+
+Install the [Keel CLI](https://github.com/marcelsud/keel#install-the-cli). Its release bundle includes the generators; TypeScript generation uses your Node.js runtime.
+
+If you own the service, put its contracts under `proto/` and run:
+
+```sh
+keel generate
+```
+
+If you consume a service from a neighboring checkout, run in your consumer project:
+
+```sh
+keel use ../notes
+```
+
+Both commands generate into `generated/` without a release or running service. `use` also saves the local dependency in `keel.json`. Run `keel generate` again after changes, or use [keel dev](https://github.com/marcelsud/keel#develop-before-releasing) to regenerate and restart your service automatically.
+
+Import the generated contract to get completion and type checking for its methods, requests, and responses. For `proto/notes/v2/notes.proto`, the generated source is `generated/notes/v2/notes_keel.ts`; use a `.js` import for your compiled application:
+
+```ts
+import { createKeel } from "@marcelsud/keel.ts";
+import { NotesServiceContract } from "./generated/notes/v2/notes_keel.js";
+
+const app = await createKeel({
+  name: "notes-client",
+  url: process.env.KEEL_URL,
+  token: process.env.KEEL_TOKEN,
+});
+
+try {
+  const notes = app.client(NotesServiceContract);
+  const note = await notes.createNote({
+    content: { text: "Hello from TypeScript" },
+  });
+  console.log(note.id);
+} finally {
+  await app.stop();
+}
+```
+
+Contracts belong to your project. See the [complete service example](https://github.com/marcelsud/keel/blob/main/examples/contracts/typescript.ts) for service registration, validation, and version migration.
+
+## Publish this SDK
+
+From a checkout of the Keel repository, install the development dependencies using the repository's setup instructions. Publishing also requires Go 1.26+ and Node.js 24+ to run the cross-language examples in the tests.
+
+Run these commands from `sdks/typescript`:
+
+```sh
+npm login
+npm publish --dry-run
+npm publish
+```
+
+Publishing runs the tests and builds the package. Packing with `npm pack` also builds it. Consumers receive JavaScript, TypeScript declarations, this README, and the MIT license.
+
+For GitHub Actions, configure an [npm trusted publisher](https://docs.npmjs.com/trusted-publishers/) for this package:
+
+- GitHub owner: `marcelsud`
+- Repository: `keel`
+- Workflow filename: `publish-npm.yml`
+- Allow direct publishing with `npm publish`.
+
+For a new package, make the first publish manually, then configure its trusted publisher. The workflow uses OIDC authentication.
+
+Set the SDK version in `package.json`, then push a matching tag such as `keel.ts-v0.1.0`. You can also run **Publish TypeScript SDK** manually from GitHub Actions. Stable versions publish to `latest`; prerelease versions publish to `next` in the workflow. For a manual prerelease, use `npm publish --tag next`.
+
+## License
+
+[MIT](https://github.com/marcelsud/keel/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+import { type NatsConnection } from "@nats-io/transport-node";
+import { ServiceError } from "@nats-io/services";
+import type { DescService } from "@bufbuild/protobuf";
+import { type Contract, type ContractOptions, type Schema, type ServiceClient, type ServiceImplementation } from "./protobuf.js";
+export { ServiceError };
+export type { Contract, ContractOptions, ContractState, Schema, ServiceClient, ServiceImplementation } from "./protobuf.js";
+export declare class ValidationError extends Error {
+}
+export interface Options {
+    url?: string;
+    name: string;
+    version?: string;
+    token?: string;
+    timeout?: number;
+}
+type Request = <T>(operation: string, input: unknown) => Promise<T>;
+export declare class KV {
+    private request;
+    private scope;
+    constructor(request: Request, scope?: string);
+    namespace(namespace: string): KV;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<boolean>;
+}
+export declare class Collections {
+    private request;
+    constructor(request: Request);
+    insert(collection: string, document: Record<string, unknown>): Promise<string>;
+    get<T extends object = Record<string, unknown>>(collection: string, id: string): Promise<(T & {
+        id: string;
+    }) | null>;
+    update(collection: string, id: string, document: Record<string, unknown>): Promise<boolean>;
+    delete(collection: string, id: string): Promise<boolean>;
+}
+export interface HandlerContext {
+    kv: KV;
+    collection: Collections;
+    pubsub: {
+        publish(topic: string, payload: unknown): Promise<void>;
+    };
+    queue: {
+        enqueue(queue: string, payload: unknown): Promise<void>;
+    };
+    call<T = unknown>(service: string, action: string, input: unknown): Promise<T>;
+    client<S extends DescService>(contract: Contract<S>): ServiceClient<S>;
+    log: Pick<Console, "info" | "error">;
+}
+export declare class Keel implements HandlerContext {
+    private nc;
+    private options;
+    readonly kv: KV;
+    readonly collection: Collections;
+    readonly pubsub: HandlerContext["pubsub"];
+    readonly queue: HandlerContext["queue"];
+    readonly log: Console;
+    private endpoints;
+    private bindings;
+    private nativeService?;
+    private messages;
+    private deliveries;
+    private active;
+    private starting?;
+    private stopping?;
+    private stopped;
+    constructor(nc: NatsConnection, options: Options);
+    private declaring;
+    action<Input, Result>(definition: {
+        name: string;
+        args?: {
+            parse(value: unknown): Input;
+        };
+        handler: (ctx: HandlerContext, input: Input) => Result | Promise<Result>;
+    }): (input: Input) => Promise<Awaited<Result>>;
+    service<S extends DescService>(contract: Contract<S>, implementation: ServiceImplementation<S> | undefined, options?: ContractOptions): void;
+    client<S extends DescService>(contract: Contract<S>): ServiceClient<S>;
+    fetchContract(service: string): Promise<Schema>;
+    subscription<Payload>(topic: string, handler: (ctx: HandlerContext, payload: Payload) => unknown | Promise<unknown>, options: {
+        name: string;
+    }): void;
+    worker<Payload>(queue: string, handler: (ctx: HandlerContext, payload: Payload) => unknown | Promise<unknown>): void;
+    private bind;
+    call<T = unknown>(service: string, action: string, input: unknown): Promise<T>;
+    private request;
+    private requestBytes;
+    start(): Promise<void>;
+    private initialize;
+    private handle;
+    private consume;
+    stop(): Promise<void>;
+}
+export declare function createKeel(options: Options): Promise<Keel>;

package/dist/index.js

@@ -0,0 +1,292 @@
+import { connect } from "@nats-io/transport-node";
+import { ServiceError, Svcm } from "@nats-io/services";
+import { jetstream } from "@nats-io/jetstream";
+import { protobufClient, schemaSubject, serviceEndpoints, validateSchema, } from "./protobuf.js";
+export { ServiceError };
+const prefix = "keel.v1";
+const identifier = /^[a-zA-Z0-9_-]+$/;
+export class ValidationError extends Error {
+}
+function name(value) {
+    if (!identifier.test(value))
+        throw new ValidationError("invalid service or action name");
+}
+function nonempty(value) {
+    if (typeof value !== "string" || !value.trim())
+        throw new ValidationError("name must not be empty");
+}
+function json(value) {
+    const result = JSON.stringify(value);
+    if (result === undefined)
+        throw new ValidationError("value must be JSON serializable");
+    return result;
+}
+export class KV {
+    request;
+    scope;
+    constructor(request, scope = "") {
+        this.request = request;
+        this.scope = scope;
+    }
+    namespace(namespace) {
+        nonempty(namespace);
+        return new KV(this.request, namespace);
+    }
+    async get(key) {
+        const result = await this.request("kv_get", { namespace: this.scope, key });
+        return result.found ? result.value : undefined;
+    }
+    async set(key, value) {
+        json(value);
+        await this.request("kv_set", { namespace: this.scope, key, value });
+    }
+    delete(key) {
+        return this.request("kv_delete", { namespace: this.scope, key });
+    }
+}
+export class Collections {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    insert(collection, document) {
+        return this.request("collection_insert", { collection, document });
+    }
+    get(collection, id) {
+        return this.request("collection_get", { collection, id });
+    }
+    update(collection, id, document) {
+        return this.request("collection_update", { collection, id, document });
+    }
+    delete(collection, id) {
+        return this.request("collection_delete", { collection, id });
+    }
+}
+export class Keel {
+    nc;
+    options;
+    kv;
+    collection;
+    pubsub;
+    queue;
+    log = console;
+    endpoints = new Map();
+    bindings = [];
+    nativeService;
+    messages = [];
+    deliveries = [];
+    active = new Set();
+    starting;
+    stopping;
+    stopped = false;
+    constructor(nc, options) {
+        this.nc = nc;
+        this.options = options;
+        const request = (operation, input) => this.request(`${prefix}.core.${operation}`, input);
+        this.kv = new KV(request);
+        this.collection = new Collections(request);
+        this.pubsub = { publish: async (topic, payload) => {
+                json(payload);
+                await request("publish", { topic, payload });
+            } };
+        this.queue = { enqueue: async (topic, payload) => {
+                json(payload);
+                await request("enqueue", { topic, payload });
+            } };
+    }
+    declaring() {
+        if (this.starting || this.stopped)
+            throw new Error("declare actions and consumers before start");
+    }
+    action(definition) {
+        this.declaring();
+        name(definition.name);
+        if (this.endpoints.has(definition.name))
+            throw new Error(`duplicate action: ${definition.name}`);
+        const invoke = async (payload) => {
+            let input = payload;
+            if (definition.args) {
+                try {
+                    input = definition.args.parse(payload);
+                }
+                catch (error) {
+                    throw new ValidationError(error instanceof Error ? error.message : "invalid input");
+                }
+            }
+            return definition.handler(this, input);
+        };
+        this.endpoints.set(definition.name, {
+            subject: `${prefix}.actions.${this.options.name}.${definition.name}`,
+            handler: async (data) => {
+                let input;
+                try {
+                    input = JSON.parse(new TextDecoder().decode(data));
+                }
+                catch {
+                    throw new ValidationError("input must be JSON");
+                }
+                return new TextEncoder().encode(json(await invoke(input)));
+            },
+        });
+        return (input) => this.call(this.options.name, definition.name, input);
+    }
+    service(contract, implementation, options = {}) {
+        this.declaring();
+        const routes = serviceEndpoints(contract, implementation, options, this);
+        for (const name of routes.keys())
+            if (this.endpoints.has(name))
+                throw new Error(`duplicate contract: ${contract.service.typeName}`);
+        for (const [name, route] of routes)
+            this.endpoints.set(name, route);
+    }
+    client(contract) {
+        return protobufClient(contract, (subject, data) => this.requestBytes(subject, data));
+    }
+    async fetchContract(service) {
+        return validateSchema(await this.request(schemaSubject(service), null), service);
+    }
+    subscription(topic, handler, options) {
+        this.bind({ kind: "subscription", topic, name: options?.name, handler: handler });
+    }
+    worker(queue, handler) {
+        this.bind({ kind: "worker", topic: queue, name: queue, handler: handler });
+    }
+    bind(binding) {
+        this.declaring();
+        nonempty(binding.topic);
+        nonempty(binding.name);
+        if (this.bindings.some((b) => b.kind === binding.kind && b.topic === binding.topic && b.name === binding.name)) {
+            throw new Error("duplicate consumer");
+        }
+        this.bindings.push(binding);
+    }
+    call(service, action, input) {
+        name(service);
+        name(action);
+        return this.request(`${prefix}.actions.${service}.${action}`, input);
+    }
+    async request(subject, input) {
+        const data = await this.requestBytes(subject, new TextEncoder().encode(json(input)));
+        return JSON.parse(new TextDecoder().decode(data));
+    }
+    async requestBytes(subject, data) {
+        if (this.nc.isClosed())
+            throw new Error("app is stopped");
+        const message = await this.nc.request(subject, data, { timeout: this.options.timeout ?? 5000 });
+        const error = ServiceError.toServiceError(message);
+        if (error)
+            throw error;
+        return message.data;
+    }
+    start() {
+        if (this.stopped)
+            return Promise.reject(new Error("app is stopped"));
+        this.starting ??= this.initialize().catch((error) => { this.starting = undefined; throw error; });
+        return this.starting;
+    }
+    async initialize() {
+        try {
+            this.nativeService = await new Svcm(this.nc).add({ name: this.options.name, version: this.options.version ?? "0.1.0" });
+            for (const [name, route] of this.endpoints) {
+                this.nativeService.addEndpoint(name, {
+                    subject: route.subject, metadata: route.metadata,
+                    handler: (error, message) => {
+                        if (error) {
+                            this.log.error("action subscription failed", error);
+                            return;
+                        }
+                        if (this.stopped) {
+                            message.respondError(503, "app is stopping");
+                            return;
+                        }
+                        const task = this.handle(message, route.handler);
+                        this.active.add(task);
+                        void task.finally(() => this.active.delete(task));
+                    },
+                });
+            }
+            const js = jetstream(this.nc);
+            for (const binding of this.bindings) {
+                const info = await this.request(`${prefix}.core.consumer`, {
+                    kind: binding.kind, topic: binding.topic, name: binding.name,
+                });
+                const consumer = await js.consumers.get(info.stream, info.consumer);
+                this.messages.push(await consumer.consume({ max_messages: 1, expires: 1000 }));
+            }
+            await this.nc.flush();
+            this.deliveries = this.messages.map((messages, index) => this.consume(messages, this.bindings[index].handler));
+        }
+        catch (error) {
+            await Promise.all(this.messages.map((messages) => messages.close()));
+            this.messages = [];
+            await this.nativeService?.stop();
+            this.nativeService = undefined;
+            throw error;
+        }
+    }
+    async handle(message, handler) {
+        try {
+            message.respond(await handler(message.data));
+        }
+        catch (error) {
+            if (error instanceof ValidationError)
+                message.respondError(400, error.message);
+            else if (error instanceof ServiceError)
+                message.respondError(error.code, error.message);
+            else {
+                this.log.error("action failed", error);
+                message.respondError(500, "handler failed");
+            }
+        }
+    }
+    async consume(messages, handler) {
+        try {
+            for await (const message of messages) {
+                if (this.stopped) {
+                    message.nak();
+                    continue;
+                }
+                const heartbeat = setInterval(() => message.working(), 10_000);
+                try {
+                    await handler(this, message.json());
+                    await message.ackAck();
+                }
+                catch (error) {
+                    this.log.error("delivery failed", error);
+                    message.nak(1000);
+                }
+                finally {
+                    clearInterval(heartbeat);
+                }
+            }
+        }
+        catch (error) {
+            if (!this.stopped)
+                this.log.error("consumer stopped", error);
+        }
+    }
+    stop() {
+        this.stopped = true;
+        this.stopping ??= (async () => {
+            try {
+                await this.starting?.catch(() => { });
+                await this.nativeService?.stop();
+                await Promise.all(this.messages.map((messages) => messages.close()));
+                await Promise.all(this.deliveries);
+                await Promise.all(this.active);
+                await this.nc.drain();
+            }
+            finally {
+                await this.nc.close();
+            }
+        })();
+        return this.stopping;
+    }
+}
+export async function createKeel(options) {
+    name(options.name);
+    if (options.name === "keel-core")
+        throw new ValidationError("reserved service name");
+    const nc = await connect({ servers: options.url ?? "nats://127.0.0.1:4222", token: options.token, name: options.name, timeout: 5000 });
+    return new Keel(nc, options);
+}

package/dist/protobuf.d.ts

@@ -0,0 +1,33 @@
+import { type DescService, type MessageInitShape, type MessageShape } from "@bufbuild/protobuf";
+import type { HandlerContext } from "./index.js";
+export type ContractState = "active" | "deprecated" | "retired";
+export interface Contract<S extends DescService = DescService> {
+    service: S;
+    schema: string;
+}
+export interface ContractOptions {
+    state?: ContractState;
+    replacement?: string;
+}
+export interface Schema {
+    service: string;
+    sha256: string;
+    state: ContractState;
+    replacement?: string;
+    descriptorSet: string;
+}
+export type ServiceImplementation<S extends DescService> = {
+    [K in keyof S["method"]]: S["method"][K]["methodKind"] extends "unary" ? (ctx: HandlerContext, input: MessageShape<S["method"][K]["input"]>) => MessageInitShape<S["method"][K]["output"]> | Promise<MessageInitShape<S["method"][K]["output"]>> : never;
+};
+export type ServiceClient<S extends DescService> = {
+    [K in keyof S["method"]]: S["method"][K]["methodKind"] extends "unary" ? (input: MessageInitShape<S["method"][K]["input"]>) => Promise<MessageShape<S["method"][K]["output"]>> : never;
+};
+export interface BinaryEndpoint {
+    subject: string;
+    handler(data: Uint8Array): Promise<Uint8Array>;
+    metadata?: Record<string, string>;
+}
+export declare function schemaSubject(service: string): string;
+export declare function serviceEndpoints<S extends DescService>(contract: Contract<S>, implementation: ServiceImplementation<S> | undefined, options: ContractOptions, context: HandlerContext): Map<string, BinaryEndpoint>;
+export declare function protobufClient<S extends DescService>(contract: Contract<S>, request: (subject: string, data: Uint8Array) => Promise<Uint8Array>): ServiceClient<S>;
+export declare function validateSchema(value: Schema, service: string): Promise<Schema>;

package/dist/protobuf.js

@@ -0,0 +1,104 @@
+import { create, createFileRegistry, fromBinary, toBinary, } from "@bufbuild/protobuf";
+import { FileDescriptorSetSchema } from "@bufbuild/protobuf/wkt";
+import { ServiceError } from "@nats-io/services";
+const prefix = "keel.v1";
+const encoder = new TextEncoder();
+const qualifiedName = /^[a-zA-Z_]\w*(?:\.[a-zA-Z_]\w*)+$/;
+function decode(value) {
+    return Uint8Array.from(atob(value), (character) => character.charCodeAt(0));
+}
+async function digest(data) {
+    const bytes = new Uint8Array(await crypto.subtle.digest("SHA-256", new Uint8Array(data)));
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export function schemaSubject(service) {
+    if (!qualifiedName.test(service))
+        throw new Error("invalid contract name");
+    return `${prefix}.schema.${service}`;
+}
+function rpcSubject(service, method) { return `${prefix}.rpc.${service}.${method}`; }
+function endpointName(kind, subject) {
+    return `${kind}_${btoa(subject).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "")}`;
+}
+function descriptor(data, service) {
+    const registry = createFileRegistry(fromBinary(FileDescriptorSetSchema, data));
+    const result = registry.getService(service);
+    if (!result)
+        throw new Error(`contract does not contain service ${service}`);
+    if (result.methods.some((method) => method.methodKind !== "unary"))
+        throw new Error("streaming RPCs are not supported");
+    return result;
+}
+export function serviceEndpoints(contract, implementation, options, context) {
+    const service = contract.service;
+    schemaSubject(service.typeName);
+    const data = decode(contract.schema);
+    const embedded = descriptor(data, service.typeName);
+    const state = options.state ?? (service.proto.options?.deprecated ? "deprecated" : "active");
+    const replacement = options.replacement;
+    if (!["active", "deprecated", "retired"].includes(state))
+        throw new Error("invalid contract state");
+    if (replacement !== undefined && !qualifiedName.test(replacement))
+        throw new Error("replacement must be a qualified contract name");
+    if (embedded.methods.length !== service.methods.length)
+        throw new Error("contract method mismatch");
+    const metadata = { contract: service.typeName, state, replacement: replacement ?? "" };
+    const routes = new Map();
+    routes.set(endpointName("schema", service.typeName), {
+        subject: schemaSubject(service.typeName), metadata,
+        handler: async () => encoder.encode(JSON.stringify({
+            service: service.typeName, sha256: await digest(data), state, replacement, descriptorSet: contract.schema,
+        })),
+    });
+    for (const method of service.methods) {
+        const declared = embedded.methods.find((candidate) => candidate.name === method.name);
+        if (!declared || declared.input.typeName !== method.input.typeName || declared.output.typeName !== method.output.typeName || method.methodKind !== "unary") {
+            throw new Error("contract method mismatch");
+        }
+        const handler = implementation?.[method.localName];
+        if (state !== "retired" && typeof handler !== "function")
+            throw new Error(`missing handler for ${method.name}`);
+        routes.set(endpointName("rpc", `${service.typeName}.${method.name}`), {
+            subject: rpcSubject(service.typeName, method.name), metadata,
+            handler: async (bytes) => {
+                if (state === "retired")
+                    throw new ServiceError(410, `API retired; replacement: ${replacement ?? ""}`);
+                let input;
+                try {
+                    input = fromBinary(method.input, bytes);
+                }
+                catch {
+                    throw new ServiceError(400, "invalid protobuf request");
+                }
+                // Reflection erases method-specific types here; the public mapped type checks both sides.
+                const invoke = handler;
+                return toBinary(method.output, create(method.output, await invoke(context, input)));
+            },
+        });
+    }
+    return routes;
+}
+export function protobufClient(contract, request) {
+    schemaSubject(contract.service.typeName);
+    const result = Object.create(null);
+    for (const method of contract.service.methods) {
+        if (method.methodKind !== "unary")
+            throw new Error("streaming RPCs are not supported");
+        result[method.localName] = async (input) => {
+            const data = toBinary(method.input, create(method.input, input));
+            return fromBinary(method.output, await request(rpcSubject(contract.service.typeName, method.name), data));
+        };
+    }
+    return result;
+}
+export async function validateSchema(value, service) {
+    if (value.service !== service || !["active", "deprecated", "retired"].includes(value.state))
+        throw new Error("invalid contract metadata");
+    if (value.replacement !== undefined && !qualifiedName.test(value.replacement))
+        throw new Error("invalid replacement contract");
+    const data = decode(value.descriptorSet);
+    if (await digest(data) !== value.sha256)
+        throw new Error("contract checksum mismatch");
+    descriptor(data, service);
+    return value;
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@marcelsud/keel.ts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Keel services, typed clients, storage, events, and background jobs.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist/*.js", "dist/*.d.ts", "README.md", "LICENSE"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marcelsud/keel.git",
+    "directory": "sdks/typescript"
+  },
+  "homepage": "https://github.com/marcelsud/keel#readme",
+  "bugs": { "url": "https://github.com/marcelsud/keel/issues" },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
+    "typecheck": "tsc -p test/tsconfig.json",
+    "example:service": "npm run build && node ../../examples/contracts/typescript.ts",
+    "test": "npm run build && npm run typecheck && node --test test/*.test.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "engines": { "node": ">=22" },
+  "dependencies": {
+    "@bufbuild/protobuf": "2.16.0",
+    "@nats-io/transport-node": "3.4.0",
+    "@nats-io/services": "3.4.0",
+    "@nats-io/jetstream": "3.4.0"
+  },
+  "devDependencies": { "@bufbuild/protoc-gen-es": "2.16.0", "typescript": "5.9.3" }
+}