@mida-context/sdk 0.1.0

package/dist/types/sdk/connect.d.ts

@@ -0,0 +1,88 @@
+import type { Deployment } from "../chain/index.js";
+import type { AccessRequest, Address, Hex } from "../protocol/index.js";
+import { MidaAgent } from "./agent.js";
+import type { AccessRequestInput, Grant } from "./agent.js";
+import type { AccessRequestStore, StoredAccessRequest } from "./request-store.js";
+/**
+ * The public endpoints the published CLI and this SDK default to — the same constants
+ * `apps/midad` uses, re-exported there so there is one definition. "off" anywhere a URL is
+ * accepted opts back into the local store or self-paid gas.
+ */
+export declare const HOSTED_STORAGE_URL = "https://store.midacontext.xyz";
+export declare const HOSTED_SPONSOR_URL = "https://sponsor.midacontext.xyz";
+/** An agent identity as `mida init` writes it, or as an integrator holds it out-of-band. */
+export interface ConnectIdentity {
+    agentId: Hex;
+    signerPrivateKey: Hex;
+    encryptionPrivateKey: Hex | Uint8Array;
+    callbackOrigin: string;
+}
+/**
+ * The network to connect to. Every field is optional: with no `network` at all the defaults are
+ * Monad testnet's public RPC, the embedded deployment record, the hosted store and the hosted
+ * sponsor. `"off"` on `storageUrl` means "the Context API the local daemon is serving" (home
+ * mode discovers it from `api-url.json`); on `sponsorUrl` it means "this wallet pays its own gas".
+ */
+export interface ConnectNetwork {
+    rpcUrl?: string;
+    deployment?: Deployment;
+    storageUrl?: string;
+    sponsorUrl?: string;
+}
+export interface ConnectOptions {
+    /**
+     * Home mode: the name `mida init` provisioned the agent under. The identity, the grants
+     * completed so far, the owner address and the network all load from the Mida home
+     * (`midaHome`, `$MIDA_HOME`, or `~/.mida`), and `requestAccess` files the pending request
+     * where `mida approve <name>` finds it.
+     */
+    name?: string;
+    /** The Mida home directory. Default: `$MIDA_HOME`, then `~/.mida`. */
+    midaHome?: string;
+    /** Environment overrides; defaults to `process.env`. `MIDA_HOME`, `MONAD_TESTNET_RPC`,
+     *  `MIDA_STORAGE_URL`, `MIDA_SPONSOR_URL` and `MIDA_DEPLOYMENTS_DIR` are read. */
+    env?: Record<string, string | undefined>;
+    /**
+     * Explicit mode: the identity fields directly, no home files read. `owner` is then required —
+     * it is the owner address the agent will ask about and write under.
+     */
+    identity?: ConnectIdentity;
+    owner?: Address;
+    network?: ConnectNetwork;
+    /** Defaults to the home-backed store in home mode, in-memory otherwise. */
+    requests?: AccessRequestStore;
+    /** Completed grants from an earlier run; in home mode `grants.json` is loaded when this is omitted. */
+    grants?: readonly Grant[];
+}
+/** What `connectAgent` returns: the agent plus the owner it connects to. */
+export interface ConnectedAgent {
+    agent: MidaAgent;
+    owner: Address;
+    /** Present in home mode. */
+    name?: string;
+    /** Present in home mode — the directory the connection was loaded from. */
+    midaHome?: string;
+    /**
+     * `agent.createAccessRequest` plus, in home mode, recording the request as the pending one the
+     * owner's `mida approve <name>` acts on. In explicit mode the returned request must reach the
+     * owner's approval path some other way.
+     */
+    requestAccess(input: AccessRequestInput): Promise<AccessRequest>;
+}
+/** A durable request store as one folder of `<requestId>.json` files plus `.consumed` markers —
+ *  the same layout the Mida home keeps under `requests/<name>/`, so `mida approve` can complete a
+ *  request this store saved. */
+export declare class FileAccessRequestStore implements AccessRequestStore {
+    #private;
+    constructor(dir: string);
+    save(request: AccessRequest): Promise<void>;
+    load(requestId: Hex): Promise<StoredAccessRequest | undefined>;
+    markConsumed(requestId: Hex): Promise<void>;
+}
+/**
+ * Connects an agent to a Mida owner. This is the SDK's front door: it builds the chain context,
+ * the Context API client and the `MidaAgent` from the provisioned identity (home mode) or fields
+ * passed directly (explicit mode) — the pieces a consumer could never construct from the public
+ * entry alone.
+ */
+export declare function connectAgent(options: ConnectOptions): ConnectedAgent;

package/dist/types/sdk/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./request-store.js";
+export * from "./agent.js";
+export * from "./batched.js";
+export * from "./connect.js";
+export { PERMISSION, PROVENANCE_POLICY } from "../protocol/index.js";
+export type { AccessRequest, Address, Hex, PurposeId } from "../protocol/index.js";
+export type { ScopeInput } from "../grant-advisor/index.js";

package/dist/types/sdk/request-store.d.ts

@@ -0,0 +1,26 @@
+import type { AccessRequest, Hex } from "../protocol/index.js";
+export interface StoredAccessRequest {
+    request: AccessRequest;
+    consumed: boolean;
+}
+/** Where `createAccessRequest` persists originals by requestId so `completeAccessRequest` can check against them (§13.3). */
+export interface AccessRequestStore {
+    save(request: AccessRequest): Promise<void>;
+    load(requestId: Hex): Promise<StoredAccessRequest | undefined>;
+    /**
+     * Compare-and-set the consumed flag in one atomic step: rejects with REQUEST_CONSUMED when the requestId is already
+     * consumed. The check in `completeAccessRequest` is only a fast path; this guard is the real "a request completes at
+     * most once" invariant, so durable stores must keep the same atomicity (for example a conditional UPDATE).
+     */
+    markConsumed(requestId: Hex): Promise<void>;
+}
+/**
+ * In-memory store for Project 1. A consumed entry is kept for the life of the process so a requestId can never be
+ * completed twice. Production agents persist this across restarts.
+ */
+export declare class MemoryAccessRequestStore implements AccessRequestStore {
+    #private;
+    save(request: AccessRequest): Promise<void>;
+    load(requestId: Hex): Promise<StoredAccessRequest | undefined>;
+    markConsumed(requestId: Hex): Promise<void>;
+}

package/dist/types/storage/index.d.ts

@@ -0,0 +1,23 @@
+import type { Hex, StorageRef } from "../protocol/index.js";
+/** §9.2 */
+export interface ContextStorage {
+    put(blob: Uint8Array): Promise<StorageRef[]>;
+    get(hash: Hex, hints?: StorageRef[]): Promise<Uint8Array>;
+}
+export declare function contentHash(blob: Uint8Array): Hex;
+/** Every get path calls this before returning bytes. */
+export declare function verifyContent(hash: Hex, blob: Uint8Array): Uint8Array;
+export declare class MemoryStorage implements ContextStorage {
+    #private;
+    /** Tests may pass a shared map to simulate a provider that returns the wrong bytes. */
+    constructor(blobs?: Map<Hex, Uint8Array>);
+    put(blob: Uint8Array): Promise<StorageRef[]>;
+    get(hash: Hex, _hints?: StorageRef[]): Promise<Uint8Array>;
+}
+export declare class FsStorage implements ContextStorage {
+    #private;
+    constructor(directory: string);
+    pathFor(hash: Hex): string;
+    put(blob: Uint8Array): Promise<StorageRef[]>;
+    get(hash: Hex, _hints?: StorageRef[]): Promise<Uint8Array>;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@mida-context/sdk",
+  "version": "0.1.0",
+  "description": "Give your agent the memory a user approved: read and write it through the user's Mida.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/damli40/mida-context.git",
+    "directory": "publish/sdk"
+  },
+  "homepage": "https://github.com/damli40/mida-context#readme",
+  "bugs": {
+    "url": "https://github.com/damli40/mida-context/issues"
+  },
+  "keywords": [
+    "ai-agents",
+    "memory",
+    "sdk",
+    "mcp",
+    "monad"
+  ],
+  "dependencies": {
+    "@hono/node-server": "1.19.17",
+    "@noble/ciphers": "2.4.0",
+    "@noble/curves": "2.4.0",
+    "@noble/hashes": "2.4.0",
+    "canonicalize": "4.0.0",
+    "hono": "4.13.7",
+    "ox": "1.7.4",
+    "permissionless": "0.4.1",
+    "viem": "2.56.3"
+  }
+}