@partite-ai/particle-kv 0.1.0

package/README.md

@@ -0,0 +1,28 @@
+# @partite-ai/particle-kv
+
+TypeScript types for the `@partite-ai/particle-kv` built-in
+consumed by [Particle](https://github.com/partite-ai/particles) particles.
+
+Types only — the runtime implementation lives in the Particle wasm
+runtime. The store is per-particle: two particles using the same key
+see independent values. Unlike credentials or HTTP, KV is not a
+capability you declare — every particle gets a key/value store
+unconditionally.
+
+```ts
+import { kv } from "@partite-ai/particle-kv";
+
+await kv.set("last-run", new Date().toISOString());
+const last = await kv.get("last-run"); // string | null
+const keys = await kv.list("user:");   // string[]
+```
+
+## API
+
+- `kv.get(key)` — `string | null`
+- `kv.set(key, value)` — replace or create
+- `kv.delete(key)` — idempotent
+- `kv.list(prefix)` — keys with that prefix, unspecified order
+
+See the [Particle README](https://github.com/partite-ai/particles) for
+the manifest schema.

package/index.d.ts

@@ -0,0 +1,24 @@
+// TypeScript types for the host-provided `@partite-ai/particle-kv`
+// module. The runtime resolves this import to a JS shim that wraps
+// the WIT-imported `particle:host/kv@0.1.0` interface — see the
+// Particle repository for the implementation. Types only.
+
+/**
+ * Per-particle key/value store. Strings only — base64-encode
+ * binary if you must. Keys and values are scoped by particle name;
+ * two particles using the same key see independent values.
+ */
+export const kv: {
+  /** Returns the stored string, or null if no entry exists. */
+  get(key: string): Promise<string | null>;
+  /** Replaces or creates the entry. */
+  set(key: string, value: string): Promise<void>;
+  /** Idempotent — removing an absent key is fine. */
+  delete(key: string): Promise<void>;
+  /** Returns keys with the given prefix, in unspecified order. */
+  list(prefix: string): Promise<string[]>;
+};
+
+export type KVError =
+  | { tag: "storage-error"; val: string }
+  | { tag: "quota-exceeded" };

package/index.js

@@ -0,0 +1,10 @@
+// This package ships TypeScript types only. The runtime
+// implementation is provided by the Particle wasm runtime — see
+// components/runtime/src/host-shim.ts in the Particle repo.
+// Loading this file outside that runtime throws so the misuse is
+// loud rather than silent.
+throw new Error(
+  "@partite-ai/particle-kv is only callable inside the Particle runtime. " +
+    "Run your particle with `particle run` / `particle serve-mcp`, or build it into " +
+    "a .particle artifact.",
+);

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@partite-ai/particle-kv",
+  "version": "0.1.0",
+  "description": "TypeScript types for `@partite-ai/particle-kv` — per-particle persistent key/value store for Particle particles.",
+  "license": "MIT",
+  "homepage": "https://github.com/partite-ai/particles",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/partite-ai/particles.git",
+    "directory": "js-types/particle-kv"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "keywords": ["particle", "wasm", "kv", "storage", "mcp"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false
+}