@alienplatform/bindings 1.0.0 → 2.0.0

package/dist/native.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `@alienplatform/bindings/native` — static-embed entry for `bun build --compile`.
+ *
+ * This module imports the native addon through the literal specifier
+ * `./alien-bindings.node` so bun's compiler can detect the reference and embed
+ * the addon into the single-file executable. Unlike the default entry, it does
+ * NOT probe the filesystem or resolve a prebuild package — the addon must
+ * already be staged next to the built `native.js`.
+ *
+ * Staging contract (produced by `alien build`'s TypeScript toolchain; see
+ * PACKAGE_LAYOUT.md): before this module is bundled and compiled, the correct
+ * per-platform addon is copied next to `dist/native.js` as
+ * `alien-bindings.node`. The build owns that copy step; this module only
+ * consumes the staged file.
+ *
+ * The specifier is kept external at build time (see tsdown.config.ts) so the
+ * literal survives into `dist/native.js` for bun to resolve and embed.
+ *
+ * `bun build --compile` on this entry needs `--format=cjs` or the produced
+ * binary crashes on load (`__require is not defined`) — see
+ * `packages/package-layout/steps/compile.ts` for the verified repro and required flag.
+ */
+/**
+ * Register the bun-embedded addon with the default loader, so plain
+ * `@alienplatform/bindings` imports (which go through `loader.ts`) resolve to
+ * it inside a compiled binary. `alien build` emits an explicit call to this
+ * from the compiled entry — an explicit call rather than a bare side-effect
+ * import so it survives this package's `sideEffects: false` tree-shaking.
+ */
+export declare function installEmbeddedAddon(): void;
+/** Resolve the storage binding named `name`. */
+export declare const storage: (name: string) => import("./types.js").Storage;
+/** Resolve the key-value binding named `name`. */
+export declare const kv: (name: string) => import("./types.js").Kv;
+/** Resolve the queue binding named `name`. */
+export declare const queue: (name: string) => import("./types.js").Queue;
+/** Resolve the vault binding named `name`. */
+export declare const vault: (name: string) => import("./types.js").Vault;
+export { AlienError, BindingNotConfiguredError, defineError } from "./errors.js";
+export type { Kv, KvScanItem, KvScanResult, KvSetOptions, ObjectMeta, PresignedRequest, Queue, QueueMessage, SignedUrlMethod, SignedUrlOptions, Storage, Vault, } from "./types.js";
+//# sourceMappingURL=native.d.ts.map

package/dist/native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH;;;;;;GAMG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAID,gDAAgD;AAChD,eAAO,MAAM,OAAO,gDAAoB,CAAA;AACxC,kDAAkD;AAClD,eAAO,MAAM,EAAE,2CAAe,CAAA;AAC9B,8CAA8C;AAC9C,eAAO,MAAM,KAAK,8CAAkB,CAAA;AACpC,8CAA8C;AAC9C,eAAO,MAAM,KAAK,8CAAkB,CAAA;AAEpC,OAAO,EAAE,UAAU,EAAE,yBAAyB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEhF,YAAY,EACV,EAAE,EACF,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,KAAK,EACL,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,OAAO,EACP,KAAK,GACN,MAAM,YAAY,CAAA"}

package/dist/native.js

@@ -0,0 +1,46 @@
+import { a as BindingNotConfiguredError, i as AlienError, n as registerEmbeddedAddon, o as defineError, r as createFactories } from "./loader.js";
+import addon from "./alien-bindings.node";
+//#region src/native.ts
+/**
+* `@alienplatform/bindings/native` — static-embed entry for `bun build --compile`.
+*
+* This module imports the native addon through the literal specifier
+* `./alien-bindings.node` so bun's compiler can detect the reference and embed
+* the addon into the single-file executable. Unlike the default entry, it does
+* NOT probe the filesystem or resolve a prebuild package — the addon must
+* already be staged next to the built `native.js`.
+*
+* Staging contract (produced by `alien build`'s TypeScript toolchain; see
+* PACKAGE_LAYOUT.md): before this module is bundled and compiled, the correct
+* per-platform addon is copied next to `dist/native.js` as
+* `alien-bindings.node`. The build owns that copy step; this module only
+* consumes the staged file.
+*
+* The specifier is kept external at build time (see tsdown.config.ts) so the
+* literal survives into `dist/native.js` for bun to resolve and embed.
+*
+* `bun build --compile` on this entry needs `--format=cjs` or the produced
+* binary crashes on load (`__require is not defined`) — see
+* `packages/package-layout/steps/compile.ts` for the verified repro and required flag.
+*/
+/**
+* Register the bun-embedded addon with the default loader, so plain
+* `@alienplatform/bindings` imports (which go through `loader.ts`) resolve to
+* it inside a compiled binary. `alien build` emits an explicit call to this
+* from the compiled entry — an explicit call rather than a bare side-effect
+* import so it survives this package's `sideEffects: false` tree-shaking.
+*/
+function installEmbeddedAddon() {
+	registerEmbeddedAddon(addon);
+}
+const factories = createFactories(() => addon);
+/** Resolve the storage binding named `name`. */
+const storage = factories.storage;
+/** Resolve the key-value binding named `name`. */
+const kv = factories.kv;
+/** Resolve the queue binding named `name`. */
+const queue = factories.queue;
+/** Resolve the vault binding named `name`. */
+const vault = factories.vault;
+//#endregion
+export { AlienError, BindingNotConfiguredError, defineError, installEmbeddedAddon, kv, queue, storage, vault };

package/dist/types.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Public types for `@alienplatform/bindings`: the four resource handle
+ * interfaces and their operation option/result shapes. These mirror the Rust
+ * `alien-bindings` handles; the native (napi) surface is an internal detail.
+ */
+/** Metadata for a single stored object. */
+export interface ObjectMeta {
+    /** Object location (path) within the store. */
+    location: string;
+    /** Object size in bytes. */
+    size: number;
+    /** Last-modified timestamp as an RFC 3339 string. */
+    lastModified: string;
+}
+/** HTTP method a presigned request may be issued for. */
+export type SignedUrlMethod = "GET" | "PUT" | "DELETE";
+/** Options for {@link Storage.signedUrl}. */
+export interface SignedUrlOptions {
+    /** Which operation the presigned request authorizes. */
+    method: SignedUrlMethod;
+    /** Object path within the store. */
+    path: string;
+    /** Validity window, in seconds. */
+    expiresIn: number;
+}
+/**
+ * A presigned request: the URL plus the method and headers to replay it with.
+ * This is a full request description (not a bare URL) so it matches every
+ * provider, including local stores whose URL is a `local://` scheme.
+ */
+export interface PresignedRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+}
+/** A resolved object-storage binding. */
+export interface Storage {
+    /** Fetch the object at `path`. */
+    get(path: string): Promise<Buffer>;
+    /** Store `data` at `path`. */
+    put(path: string, data: Buffer | Uint8Array): Promise<void>;
+    /** Delete the object at `path`. */
+    delete(path: string): Promise<void>;
+    /** List objects, optionally filtered by `prefix`. */
+    list(prefix?: string): Promise<ObjectMeta[]>;
+    /** Fetch metadata for the object at `path`. */
+    head(path: string): Promise<ObjectMeta>;
+    /** Copy the object at `from` to `to`. */
+    copy(from: string, to: string): Promise<void>;
+    /** Create a presigned request for `path`. */
+    signedUrl(options: SignedUrlOptions): Promise<PresignedRequest>;
+}
+/** Options for {@link Kv.set}. */
+export interface KvSetOptions {
+    /** Time-to-live, in seconds. */
+    ttl?: number;
+    /** Only create the key if it does not already exist. */
+    ifNotExists?: boolean;
+}
+/** A single key-value pair returned by a scan. */
+export interface KvScanItem {
+    /** The key. */
+    key: string;
+    /** The raw value bytes. */
+    value: Buffer;
+}
+/** A page of scan results. */
+export interface KvScanResult {
+    /**
+     * Key-value pairs found on this page. Values are returned alongside their
+     * keys (the provider already reads them), so a scan needs no follow-up `get`.
+     */
+    items: KvScanItem[];
+    /** Opaque cursor for the next page, or `undefined` when exhausted. */
+    nextCursor?: string;
+}
+/** A resolved key-value binding. */
+export interface Kv {
+    /** Get the raw value bytes for `key`, or `null` if absent/expired. */
+    get(key: string): Promise<Buffer | null>;
+    /** Get the value for `key` as UTF-8 text, or `null` if absent/expired. */
+    getText(key: string): Promise<string | null>;
+    /** Get the value for `key` parsed as JSON, or `null` if absent/expired. */
+    getJson<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Set `key` to the UTF-8 `value`. With `ifNotExists`, resolves `true` when
+     * created and `false` when the key already existed; otherwise `true`.
+     */
+    set(key: string, value: string, options?: KvSetOptions): Promise<boolean>;
+    /**
+     * Set `key` to `value` serialized as JSON (via `JSON.stringify`). With
+     * `ifNotExists`, resolves `true` when created and `false` when the key already
+     * existed; otherwise `true`.
+     */
+    setJson(key: string, value: unknown, options?: KvSetOptions): Promise<boolean>;
+    /** Delete `key` (no error if absent). */
+    delete(key: string): Promise<void>;
+    /** Check whether `key` exists. */
+    exists(key: string): Promise<boolean>;
+    /** Scan keys under `prefix`, with optional pagination. */
+    scan(prefix: string, limit?: number, cursor?: string): Promise<KvScanResult>;
+}
+/** A message received from a queue. */
+export interface QueueMessage {
+    /** Payload discriminant: `"json"` or `"text"`. */
+    payloadType: "json" | "text";
+    /**
+     * The payload string: serialized JSON when `payloadType === "json"`, raw text
+     * when `payloadType === "text"`.
+     */
+    payload: string;
+    /** Opaque receipt handle for ack/nack. */
+    receiptHandle: string;
+    /**
+     * Delivery attempt, 1-based (1 = first delivery). Providers that do not report
+     * redelivery counts always set 1; use it to enforce retry limits.
+     */
+    attempt: number;
+}
+/** A resolved queue binding. */
+export interface Queue {
+    /** Send a JSON message (the object is serialized with `JSON.stringify`). */
+    send(message: unknown): Promise<void>;
+    /** Send a raw text message. */
+    sendText(text: string): Promise<void>;
+    /** Receive up to `max` messages. */
+    receive(max: number): Promise<QueueMessage[]>;
+    /** Acknowledge a message by its receipt handle. */
+    ack(receipt: string): Promise<void>;
+    /** Negative-acknowledge a message, making it immediately redeliverable. */
+    nack(receipt: string): Promise<void>;
+    /** Delete every message in the queue. */
+    purge(): Promise<void>;
+}
+/** A resolved vault (secrets) binding. */
+export interface Vault {
+    /** Get the secret named `name` as a string. */
+    get(name: string): Promise<string>;
+    /** Get the secret named `name`, parsed as JSON. */
+    getJson<T = unknown>(name: string): Promise<T>;
+    /** Create or update the secret named `name` with a string value. */
+    put(name: string, value: string): Promise<void>;
+    /** Create or update the secret named `name`, serialized as JSON. */
+    putJson(name: string, value: unknown): Promise<void>;
+    /** Delete the secret named `name`. */
+    delete(name: string): Promise<void>;
+    /** List the names of all secrets in this vault. */
+    list(): Promise<string[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,22 +1,39 @@
 {
   "name": "@alienplatform/bindings",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./native": {
+      "types": "./dist/native.d.ts",
+      "import": "./dist/native.js"
     }
   },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0.23"
+  },
   "keywords": [
     "alien",
     "bindings",
-    "grpc",
-    "sdk"
+    "storage",
+    "kv",
+    "queue",
+    "vault",
+    "napi"
   ],
-  "author": "",
-  "license": "ISC",
-  "description": "TypeScript SDK for Alien bindings - gRPC client for Storage, KV, Queue, Vault, and more",
+  "author": "Alien Software, Inc. <hi@alien.dev>",
+  "license": "FSL-1.1-Apache-2.0",
+  "description": "Direct TypeScript bindings for Alien storage, kv, queue, and vault over an in-process napi-rs addon",
+  "homepage": "https://alien.dev",
   "repository": {
     "type": "git",
     "url": "https://github.com/alienplatform/alien.git",
@@ -27,29 +44,30 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
+    "@napi-rs/cli": "^3.0.0",
     "@types/node": "^24.0.15",
-    "ts-proto": "^2.7.0",
     "tsdown": "^0.13.0",
     "typescript": "^5.8.3",
     "vitest": "^3.1.4",
+    "zod": "4.3.2",
     "@alienplatform/typescript-config": "^1.0.0"
   },
   "dependencies": {
-    "@bufbuild/protobuf": "^2.5.3",
-    "@grpc/grpc-js": "^1.13.4",
-    "long": "^5.3.2",
-    "nice-grpc": "^2.1.11",
-    "nice-grpc-common": "^2.0.2",
-    "protobufjs": "^7.5.3",
-    "ts-pattern": "^5.7.1",
-    "zod": "4.3.2",
-    "@alienplatform/core": "^1.0.1"
+    "@alienplatform/core": "^2.0.0"
+  },
+  "optionalDependencies": {
+    "@alienplatform/bindings-darwin-arm64": "2.0.0",
+    "@alienplatform/bindings-darwin-x64": "2.0.0",
+    "@alienplatform/bindings-linux-x64-gnu": "2.0.0",
+    "@alienplatform/bindings-linux-arm64-gnu": "2.0.0"
   },
   "scripts": {
-    "build": "tsdown",
-    "test": "vitest run --passWithNoTests",
+    "build": "tsdown && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "build:addon": "napi build --platform --release --cwd ../../crates/alien-bindings-node",
+    "test": "vitest run",
+    "test:bun": "bun scripts/run-bun-tests.mjs",
     "test:ts": "tsc --noEmit",
-    "generate": "./scripts/generate-proto.sh",
+    "smoke": "node scripts/smoke-envelope.mjs",
     "format-and-lint": "biome check .",
     "format-and-lint:fix": "biome check . --write"
   }

package/AGENTS.md

@@ -1,70 +0,0 @@
-# @alienplatform/bindings
-
-TypeScript SDK for Alien bindings. Provides gRPC clients for Storage, KV, Queue, Vault, Build, ArtifactRegistry, Function, and ServiceAccount.
-
-## Commands
-
-```bash
-pnpm generate  # Regenerate TypeScript from Proto
-pnpm build     # Build the package
-pnpm test:ts   # Type check
-```
-
-## Type Architecture
-
-```
-┌─────────────────┐
-│   Rust Types    │  ← Source of truth (alien-core)
-└────────┬────────┘
-         │
-    ┌────┴────┐
-    ▼         ▼
-┌───────┐  ┌───────────┐
-│ Proto │  │ OpenAPI   │
-│ (wire)│  │ (schema)  │
-└───┬───┘  └─────┬─────┘
-    │            │
-    ▼            ▼
-┌─────────┐  ┌────────────┐
-│ts-proto │  │ Kubb/Zod   │
-│(internal)│  │(@alien/core)│ ← Public API types
-└────┬────┘  └──────┬─────┘
-     │              │
-     └──────┬───────┘
-            ▼
-   Transform proto → core types
-   in binding implementations
-```
-
-**Key principle:** Domain types (`BuildStatus`, `StorageEvent`, etc.) come from `@alienplatform/core`. Proto types are internal - used only for gRPC wire format. Bindings transform proto ↔ public types.
-
-## Package Structure
-
-```
-src/
-├── generated/        # Auto-generated from Proto (DO NOT EDIT)
-├── bindings/         # Individual binding clients (see bindings/AGENTS.md)
-├── context.ts        # AlienContext - main entry point
-├── events.ts         # Event handlers (storage, cron, queue)
-├── types.ts          # SDK-specific types (options, results)
-└── index.ts          # Public exports
-```
-
-## Proto Definitions
-
-Protos live in `crates/alien-bindings/proto/`. When modified:
-
-1. Run `pnpm generate` in this package
-2. Update binding implementations to match new proto types
-3. Verify TypeScript matches Rust behavior (see `src/bindings/AGENTS.md`)
-
-## Adding New Bindings
-
-1. Add proto in `crates/alien-bindings/proto/`
-2. Run `pnpm generate`
-3. Create binding in `src/bindings/<name>.ts`
-4. Add types to `src/types.ts` (public API) 
-5. Export from `src/bindings/index.ts` and `src/index.ts`
-6. Add accessor method to `AlienContext`
-
-See `src/bindings/AGENTS.md` for implementation guidelines.