@econ-v1/app-sdk 1.0.0-experimental

package/README.md

@@ -0,0 +1,91 @@
+# @econ-v1/app-sdk
+
+> **Status: `1.0.0-experimental`** — API surface is frozen pending validation by at least two first-party packages. Breaking changes between `1.0.0-experimental.*` releases are possible. Pin to an exact version in production.
+
+TypeScript / Bun SDK for building **Node-App** plugins for the [Node](https://github.com/econ-v1/node-app-distribution) Lightning-powered marketplace daemon. Apps run as separate Bun processes and talk to the host over a Unix-domain socket using a JSON-newline protocol.
+
+## What it gives you
+
+- An abstract `NodeApp` class — extend it, declare metadata, and implement the hooks you need.
+- A declarative `route()` helper — register HTTP handlers with built-in scope checks (defense-in-depth on top of the host's manifest enforcement).
+- `invokeCapability()` — call any capability registered with the host's capability router.
+- `publishEvent()` — publish namespaced domain events to the host event bus.
+- `host.{trace,debug,info,warn,error}` — file-backed structured logging.
+
+## Quick start
+
+```sh
+bun add @econ-v1/app-sdk@1.0.0-experimental
+```
+
+```typescript
+import { NodeApp, runNodeApp, type AppRequest, type AppResponse } from "@econ-v1/app-sdk";
+
+class MyApp extends NodeApp {
+  readonly metadata = {
+    name: "my-app",
+    version: "0.1.0",
+    author: "Me",
+    description: "Hello-world Node-App",
+    capabilities: ["http_handler"],
+  };
+
+  async init() {
+    this.route("GET", "/hello", { requiredPermissions: [] }, async () =>
+      this.json({ hello: "world" }),
+    );
+  }
+}
+
+runNodeApp(new MyApp());
+```
+
+The host launches the Bun process, supplies a Unix socket via the `NODE_APP_SOCKET` environment variable, and routes proxied HTTP requests, events, and capability calls over the socket.
+
+## Defense-in-depth scope checks
+
+```typescript
+this.route(
+  "POST",
+  "/admin/**",
+  { requiredPermissions: ["payments:write"] },
+  async (req) => this.json({ ok: true }),
+);
+```
+
+The host already enforces `endpoint_policies` from your manifest before the request reaches the app — `route()` re-checks `request.caller.granted_permissions` as a second line of defense.
+
+## Calling host capabilities
+
+```typescript
+import { invokeCapability } from "@econ-v1/app-sdk";
+
+const response = await invokeCapability({
+  id: crypto.randomUUID(),
+  capability: "core.storage.get",
+  payload: { key: "user_pref" },
+});
+```
+
+## Publishing events
+
+```typescript
+import { publishEvent } from "@econ-v1/app-sdk";
+
+publishEvent("my-app.user_created", { userId: 42 });
+```
+
+Event names **must** be namespaced with the app name (`my-app.*`); the host rejects un-namespaced events.
+
+## ABI compatibility
+
+The TypeScript SDK targets **Node Host API v1** over IPC. The wire format is independently versioned but tracks the same semantics as the C ABI used by native (Rust / Go / C / Zig) apps. See `core/host-abi-v1/include/node-host-api-v1.h` for the C surface.
+
+## License
+
+Licensed under either of
+
+- Apache License, Version 2.0
+- MIT License
+
+at your option.

package/dist/index.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Node-App SDK for TypeScript/JavaScript
+ *
+ * Provides the NodeApp abstract class and runNodeApp() entry point
+ * for building scripted node-app plugins that communicate with the
+ * host backend via Unix Socket IPC using a JSON-newline protocol.
+ *
+ * Logs are written to files in the NODE_APP_LOG_DIR directory for
+ * persistence, while IPC messages are used for real-time streaming.
+ *
+ * @example
+ * ```typescript
+ * import { NodeApp, runNodeApp, host } from "@econ-v1/app-sdk";
+ *
+ * class MyApp extends NodeApp {
+ *   readonly metadata = {
+ *     name: "my-app",
+ *     version: "0.1.0",
+ *     author: "Me",
+ *     description: "My app",
+ *     capabilities: ["http_handler"],
+ *   };
+ *
+ *   async handleRequest(request: AppRequest): Promise<AppResponse> {
+ *     return { status: 200, headers: {}, body: { hello: "world" } };
+ *   }
+ * }
+ *
+ * runNodeApp(new MyApp());
+ * ```
+ */
+export interface AppMetadata {
+    name: string;
+    version: string;
+    author: string;
+    description: string;
+    capabilities: string[];
+}
+/**
+ * Caller identity set by the host proxy after validating the scoped JWT.
+ * Only present on requests that arrived through the proxy route.
+ * Apps should trust this struct — it is injected by the host over the Unix IPC socket,
+ * not derived from HTTP headers (which are stripped by the proxy).
+ */
+export interface CallerContext {
+    /** App name whose scoped JWT was used — always equals this app's name */
+    app_name: string;
+    /** Permissions granted at consent time and embedded in the scoped JWT */
+    granted_permissions: string[];
+}
+export interface AppRequest {
+    id: string;
+    method: string;
+    path: string;
+    /** HTTP headers forwarded from the client (x-node-* headers are stripped by the proxy) */
+    headers: Record<string, string>;
+    body: unknown;
+    /**
+     * Caller identity injected by the host proxy after JWT validation.
+     * null for direct/internal requests (e.g. capability invocations from the host).
+     * Use this for auth context — do NOT read x-node-* headers.
+     */
+    caller: CallerContext | null;
+}
+export interface AppResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+}
+export interface AppEvent {
+    name: string;
+    data: unknown;
+}
+export interface CapabilityRequest {
+    id: string;
+    capability: string;
+    payload: unknown;
+}
+export interface CapabilityResponse {
+    id: string;
+    success: boolean;
+    payload: unknown;
+}
+export interface CapabilityExample {
+    label: string;
+    request: unknown;
+}
+export interface ProvidedCapability {
+    name: string;
+    description: string;
+    request_schema?: unknown;
+    response_schema?: unknown;
+    priority?: number;
+    examples?: CapabilityExample[];
+}
+/**
+ * Host interaction helper for logging from within app code.
+ * Logs are written to files for persistence and sent via IPC for real-time streaming.
+ */
+export declare const host: {
+    trace: (message: string) => void;
+    debug: (message: string) => void;
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+};
+/**
+ * Invoke a capability on the host via the capability router.
+ * Returns a promise that resolves with the capability response.
+ *
+ * @param request - The capability request to invoke
+ * @param timeoutMs - Optional timeout in milliseconds (default: 30000)
+ */
+export declare function invokeCapability(request: CapabilityRequest, timeoutMs?: number): Promise<CapabilityResponse>;
+/**
+ * Publish an event to the host event bus.
+ *
+ * The event_name MUST be namespaced with the app name prefix
+ * (e.g., "my-app.status.updated"). The host validates the namespace
+ * and rejects events that do not start with "{app_name}.".
+ *
+ * This is a fire-and-forget operation — no response is returned.
+ */
+export declare function publishEvent(eventName: string, data: unknown): void;
+interface RoutePolicy {
+    /** All listed permissions must be present in request.caller.granted_permissions */
+    requiredPermissions?: string[];
+}
+type RouteHandler = (req: AppRequest) => Promise<AppResponse>;
+/**
+ * Abstract base class for TypeScript/JavaScript node-apps.
+ *
+ * Subclass this and implement handleRequest/handleEvent as needed.
+ * Prefer using `route()` for HTTP handler registration — it provides
+ * declarative scope enforcement as a defense-in-depth layer on top of
+ * the host-side manifest endpoint_policies check.
+ */
+export declare abstract class NodeApp {
+    abstract readonly metadata: AppMetadata;
+    private readonly _routes;
+    /**
+     * Register a declarative route handler with an optional scope policy.
+     *
+     * The host already enforces `endpoint_policies` from the manifest before the
+     * request reaches the app. This method provides a defense-in-depth layer:
+     * the SDK re-checks `request.caller.granted_permissions` before dispatching.
+     *
+     * @param method  HTTP method to match ("GET", "POST", "*" for any)
+     * @param path    Path glob relative to app root ("/data", "/admin/**")
+     * @param policy  Optional scope requirements
+     * @param handler Async handler called when route + policy match
+     *
+     * @example
+     * ```typescript
+     * this.route("GET", "/data", { requiredPermissions: ["payments:read"] },
+     *   async (req) => this.json(await fetchData()));
+     * ```
+     */
+    protected route(method: string, path: string, policy: RoutePolicy, handler: RouteHandler): void;
+    /**
+     * Initialize the app with configuration from the host.
+     * Override for custom initialization logic.
+     * If using `route()`, register routes here.
+     */
+    init(_config: Record<string, unknown>): Promise<void>;
+    /**
+     * Shut down the app gracefully.
+     * Override for custom cleanup logic.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Handle an incoming HTTP request proxied from the host.
+     *
+     * If routes are registered via `route()`, the base implementation dispatches
+     * automatically (with scope enforcement). Override this only for fully custom
+     * routing logic — the override bypasses the SDK-level scope check.
+     */
+    handleRequest(request: AppRequest): Promise<AppResponse>;
+    /** Internal route dispatcher — checks scope then calls handler */
+    private _dispatchRoute;
+    /**
+     * Handle a domain event forwarded from the host.
+     * Override if the app declares "event_listener" capability.
+     */
+    handleEvent(_event: AppEvent): Promise<void>;
+    /**
+     * Return the list of service capabilities this app provides.
+     * Override to declare capabilities for the capability registry.
+     * Default returns an empty list (no capabilities provided).
+     */
+    providedCapabilities(): ProvidedCapability[];
+    /**
+     * Handle a capability invocation from another app via the capability router.
+     * Override to implement capability handling logic.
+     * Default returns an error response.
+     */
+    handleCapability(_request: CapabilityRequest): Promise<CapabilityResponse>;
+    protected json(body: unknown, status?: number): AppResponse;
+    protected error(message: string, status?: number): AppResponse;
+    protected notFound(): AppResponse;
+}
+/**
+ * Connect the app to the host backend via Unix Socket IPC.
+ *
+ * The socket path is provided via the `NODE_APP_SOCKET` environment variable.
+ * The host creates the socket and waits for the app to connect.
+ *
+ * Protocol:
+ * 1. App connects to Unix socket
+ * 2. Host sends init message with config
+ * 3. App sends ready message with metadata
+ * 4. Host sends request/event messages, app responds
+ * 5. Host sends shutdown, app cleans up and exits
+ */
+export declare function runNodeApp(app: NodeApp): void;
+export {};

package/dist/index.js

@@ -0,0 +1,5 @@
+// @bun
+import{createConnection as G}from"net";import{appendFileSync as N,mkdirSync as E,existsSync as S}from"fs";import{join as x}from"path";var Y=process.env.NODE_APP_LOG_DIR,C=Y?x(Y,"app.log"):null,$=!1;function F(){if($||!Y)return;try{if(!S(Y))E(Y,{recursive:!0});$=!0}catch{}}function w(z,B){if(!C)return;if(F(),!$)return;let A=`${new Date().toISOString()} [${z.toUpperCase().padEnd(5)}] ${B}
+`;try{N(C,A)}catch{}}var R=null,Z=new Map,Q={trace:(z)=>X("trace",z),debug:(z)=>X("debug",z),info:(z)=>X("info",z),warn:(z)=>X("warn",z),error:(z)=>X("error",z)};function X(z,B){if(w(z,B),R)R({type:"log",level:z,message:B});else console[z==="trace"?"debug":z](B)}function T(z,B){if(!R)return Promise.reject(Error("Not connected to host"));let J=B??30000;return new Promise((A,O)=>{Z.set(z.id,{resolve:A,reject:O}),R({type:"invoke_capability",id:z.id,request:z}),setTimeout(()=>{if(Z.has(z.id))Z.delete(z.id),O(Error(`Capability invocation timed out after ${J}ms: ${z.capability}`))},J)})}function D(z,B){if(!R)throw Error("Not connected to host");R({type:"publish_event",event_name:z,data:B})}function M(z,B){let J=z.split("/"),A=B.split("/"),O=0,K=0;while(O<J.length){if(J[O]==="**")return!0;if(K>=A.length)return!1;if(J[O]!=="*"&&J[O]!==A[K])return!1;O++,K++}return K===A.length}class j{_routes=[];route(z,B,J,A){this._routes.push({method:z,path:B,policy:J,handler:A})}async init(z){}async shutdown(){}async handleRequest(z){if(this._routes.length>0)return this._dispatchRoute(z);return{status:501,headers:{},body:{error:"Not implemented"}}}async _dispatchRoute(z){let B=z.method.toUpperCase(),J=z.path;for(let A of this._routes){if(!(A.method==="*"||A.method.toUpperCase()===B))continue;if(!M(A.path,J))continue;let K=A.policy.requiredPermissions??[],V=z.caller?.granted_permissions??[],U=K.filter((W)=>!V.includes(W));if(U.length>0)return Q.warn(`SDK scope denied: [${U.join(", ")}] missing for ${B} ${J}`),{status:403,headers:{},body:{error:`Missing permissions: ${U.join(", ")}`}};return A.handler(z)}return this.notFound()}async handleEvent(z){}providedCapabilities(){return[]}async handleCapability(z){return{id:z.id,success:!1,payload:{error:"Capability handling not implemented"}}}json(z,B=200){return{status:B,headers:{"Content-Type":"application/json"},body:z}}error(z,B=500){return{status:B,headers:{"Content-Type":"application/json"},body:{error:z}}}notFound(){return this.error("Not found",404)}}function k(z){let B=process.env.NODE_APP_SOCKET;if(!B)console.error("[node-app-sdk] NODE_APP_SOCKET environment variable not set"),process.exit(1);let J="",A=G(B,()=>{Q.debug(`Connected to host via ${B}`)}),O=(K)=>{A.write(JSON.stringify(K)+`
+`)};R=O,A.on("data",async(K)=>{J+=K.toString("utf-8");let V;while((V=J.indexOf(`
+`))!==-1){let U=J.slice(0,V).trim();if(J=J.slice(V+1),!U)continue;try{let W=JSON.parse(U);await y(z,W,O)}catch(W){Q.error(`Failed to parse IPC message: ${W}`)}}}),A.on("error",(K)=>{console.error(`[node-app-sdk] Socket error: ${K.message}`),process.exit(1)}),A.on("close",()=>{Q.debug("Socket closed, shutting down"),process.exit(0)}),process.on("SIGTERM",async()=>{await z.shutdown(),A.end(),process.exit(0)}),process.on("SIGINT",async()=>{await z.shutdown(),A.end(),process.exit(0)})}async function y(z,B,J){switch(B.type){case"init":{let A=B.config;await z.init(A),J({type:"ready",metadata:z.metadata});break}case"request":{let{id:A,request:O}=B;try{let K=await z.handleRequest(O);J({type:"response",id:A,response:K})}catch(K){J({type:"response",id:A,response:{status:500,headers:{},body:{error:`Internal app error: ${K}`}}})}break}case"event":{let{event:A}=B;try{await z.handleEvent(A)}catch(O){Q.error(`Event handler error: ${O}`)}break}case"capability_request":{let{id:A,request:O}=B;try{let K=await z.handleCapability(O);J({type:"capability_response",id:A,response:K})}catch(K){J({type:"capability_response",id:A,response:{id:O.id,success:!1,payload:{error:`Capability handler error: ${K}`}}})}break}case"invoke_capability_result":{let{id:A,response:O}=B,K=Z.get(A);if(K)Z.delete(A),K.resolve(O);break}case"shutdown":{Q.info("Received shutdown signal from host"),await z.shutdown(),process.exit(0);break}default:Q.warn(`Unknown IPC message type: ${B.type}`)}}export{k as runNodeApp,D as publishEvent,T as invokeCapability,Q as host,j as NodeApp};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@econ-v1/app-sdk",
+  "version": "1.0.0-experimental",
+  "description": "TypeScript SDK for building Node mini-app plugins (Bun runtime) on the Lightning-powered marketplace daemon",
+  "license": "MIT OR Apache-2.0",
+  "author": "Node contributors",
+  "homepage": "https://github.com/econ-v1/node",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/econ-v1/node.git",
+    "directory": "sdk/typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/econ-v1/node/issues"
+  },
+  "keywords": [
+    "node-app",
+    "plugin",
+    "ipc",
+    "lightning",
+    "bun",
+    "sdk"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --outdir dist --target=bun --minify && tsc --emitDeclarationOnly --declaration --outDir dist",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "bun-types": "latest"
+  }
+}