usemycontext 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,121 @@
+# usemycontext
+
+The user's context, in any AI app you ship. One `npm i`, one hook, and the
+user's compiled personal context drops straight into your prompts - while
+UseMyContext stays structurally blind to the content.
+
+```bash
+npm i usemycontext
+```
+
+```jsx
+import { useMyContextReact } from "usemycontext/react";
+
+// The user pasted their UseMyContext token (grab one at usemycontext.ai/#/connect).
+// This component connects, then drops their compiled context into a prompt.
+function Assistant({ token }) {
+  const { state, connected, connect, client } = useMyContextReact();
+
+  async function run() {
+    await connect({ token });
+    const { composite } = await client.profile(); // the user's compiled context
+    const { passages } = await client.ask("what should I keep in mind?");
+    const systemPrompt =
+      `You are helping a specific person. Their context:\n${composite}\n\n` +
+      `Relevant notes:\n${passages.map((p) => p.text).join("\n")}`;
+    console.log(systemPrompt); // -> hand this to your LLM
+  }
+
+  return (
+    <button onClick={run} disabled={state === "connecting"}>
+      {connected ? "Connected" : "Use my context"}
+    </button>
+  );
+}
+```
+
+That is the whole integration. The hook holds the user's *own* token and calls
+the membrane exactly like Claude does - same trust model, new client shape.
+
+## Without React
+
+The core entry is framework-free:
+
+```js
+import { useMyContext } from "usemycontext";
+
+const ctx = useMyContext();
+await ctx.connect({ token }); // v1 is TOKEN-IN
+const { composite } = await ctx.profile();
+```
+
+## The drop-in button
+
+```jsx
+import { ConnectMyContext } from "usemycontext/react";
+
+<ConnectMyContext token={token} onConnect={(s) => console.log(s)} />;
+```
+
+It renders one `<button class="umc-connect-button" data-umc-state="...">` whose
+label tracks the connect state. Style it however you like - the markup is yours.
+
+## The 7 tools
+
+Once `connected`, the client exposes one ergonomic wrapper per MCP tool:
+
+| Method | Returns | What it is |
+|---|---|---|
+| `client.profile()` | `{ composite, facts? }` | the compiled personal context - drop into a system prompt |
+| `client.ask(query, { k? })` | `{ passages, text }` | `ask_docs` - cited passages to ground the LLM |
+| `client.listFiles()` | `FileMeta[]` | the user's files (metadata only) |
+| `client.searchFiles(query)` | `FileMeta[]` | search files by name |
+| `client.getFile(fileId)` | `{ text, downloadUrl? }` | the file's full extracted text |
+| `client.suggestUpdate(text)` | `{ id?, text }` | the one write - a PENDING suggestion the user reviews |
+| `client.sharedContext(from?)` | `{ mode, shares, composite }` | read contexts others shared with the user |
+
+## The connect state machine
+
+`ctx.state` is one of:
+
+```
+idle -> connecting -> connected
+                   \-> declined   (user/host refused)
+                   \-> error      (network / transport failure)
+connected -> expired              (token rejected mid-session - re-connect)
+<any>     -> disconnected         (disconnect() was called)
+```
+
+A 401 from the membrane (an expired or revoked token) moves the client to
+`expired` and throws `TokenExpiredError`; re-run `connect({ token })` with a
+fresh token to recover.
+
+## Errors
+
+Every failure is a typed subclass of `UseMyContextError`:
+
+- `NotConnectedError` - a wrapper was called before `connect()`.
+- `TokenExpiredError` - the membrane rejected the token (carries the
+  `WWW-Authenticate` header).
+- `ScopeDeniedError` - this connection is not authorized for that tool.
+- `ToolCallError` - the tool returned an error result.
+- `TransportError` - the network/transport failed.
+
+## Token model (v1)
+
+v1 is **token-in only**: you supply the user's UseMyContext session token to
+`connect({ token })`. The full browser-OAuth-in-the-SDK flow (a hosted popup on
+`connect.usemycontext.ai`) is v2.
+
+## Persistence
+
+The token is persisted to `localStorage` by default (a returning page starts
+`connected`). Pass `storage: null` to disable, or a custom `StorageAdapter`:
+
+```js
+useMyContext({ storage: null });
+```
+
+## License
+
+MIT

package/dist/client-mXQsH2mZ.d.cts

@@ -0,0 +1,217 @@
+/** Base class for every error the SDK throws, so callers can `catch (e)`. */
+declare class UseMyContextError extends Error {
+    constructor(message: string);
+}
+/** Thrown when a tool wrapper is called before a successful `connect()`. */
+declare class NotConnectedError extends UseMyContextError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the membrane rejects the token (HTTP 401 + WWW-Authenticate).
+ * The client also transitions to `expired` so the host can re-connect.
+ */
+declare class TokenExpiredError extends UseMyContextError {
+    /** The raw `WWW-Authenticate` header, when the server sent one. */
+    readonly wwwAuthenticate?: string;
+    constructor(message?: string, wwwAuthenticate?: string);
+}
+/** Thrown when a tool call is refused for lack of scope (membrane -32604). */
+declare class ScopeDeniedError extends UseMyContextError {
+    readonly code = -32604;
+    constructor(message: string);
+}
+/** Thrown for a JSON-RPC protocol error or a tool-level `isError` result. */
+declare class ToolCallError extends UseMyContextError {
+    /** The JSON-RPC error code, when the failure was a protocol error. */
+    readonly code?: number;
+    constructor(message: string, code?: number);
+}
+/** Thrown for transport/parse failures (network down, non-JSON body, ...). */
+declare class TransportError extends UseMyContextError {
+    constructor(message: string);
+}
+
+/**
+ * The connect state machine the hook/client exposes.
+ *
+ *  - `idle`         nothing attempted yet (the fresh client).
+ *  - `connecting`   `connect({token})` is validating the token against the
+ *                   membrane (an `initialize` round-trip).
+ *  - `connected`    a valid token is held; the 7 tool wrappers are callable.
+ *  - `declined`     the user/host explicitly refused the connection (reserved
+ *                   for the v2 OAuth popup path; a v1 token-in connect never
+ *                   enters it on its own, but the reducer models it).
+ *  - `expired`      a previously-`connected` token was rejected by the membrane
+ *                   (a 401 + WWW-Authenticate); the host should re-connect.
+ *  - `error`        a non-auth failure (network/transport/parse) ended a connect
+ *                   or a wrapper call.
+ *  - `disconnected` `disconnect()` was called; the token is cleared.
+ */
+type ConnectState = "idle" | "connecting" | "connected" | "declined" | "expired" | "error" | "disconnected";
+/** One file's metadata as returned by `list_files` / `search_files`. */
+interface FileMeta {
+    id: string;
+    name: string;
+    size: number;
+    contentType: string;
+    modified: string;
+    /** Owner-side processing status; may be absent on legacy shapes. */
+    status?: "not-processed" | "processing" | "available" | "error";
+}
+/** The compiled personal context the `profile` tool serves. */
+interface ProfileResult {
+    /**
+     * The compiled composite text, ready to drop into a system prompt. When the
+     * user has no compiled context yet, the membrane falls back to raw facts and
+     * this is the JSON of `{ facts: [...] }` rendered as text - in that case
+     * `facts` is populated and `composite` is the same string.
+     */
+    composite: string;
+    /** Raw facts, present only when the membrane fell back (no compile yet). */
+    facts?: string[];
+}
+/** One cited passage returned by `ask_docs`. */
+interface AskPassage {
+    /** 1-based citation index as rendered by the membrane. */
+    index: number;
+    /** The passage text the LLM should reason over and quote. */
+    text: string;
+    /** The source file the passage was cited from (when present). */
+    file?: string;
+    /** The access scope (the owning user id) as cited. */
+    scope?: string;
+    /** The retrieval score (higher = more relevant), when present. */
+    score?: number;
+}
+/** The result of an `ask_docs` call. */
+interface AskResult {
+    /** The cited passages, in rank order. Empty when nothing matched. */
+    passages: AskPassage[];
+    /** The raw rendered text the membrane returned (citations + passages). */
+    text: string;
+}
+/** The result of a `get_file` call. */
+interface GetFileResult {
+    /** The full rendered text the membrane returned for the file. */
+    text: string;
+    /** A short-lived download link, parsed out of the rendered text when present. */
+    downloadUrl?: string;
+}
+/** The result of a `suggest_update` call (the one write tool). */
+interface SuggestUpdateResult {
+    /** The candidate id the membrane assigned, when it could be parsed. */
+    id?: string;
+    /** The full rendered acknowledgement text. */
+    text: string;
+}
+/** One share listed by `shared_context` (LIST mode). */
+interface SharedContextEntry {
+    /** Who shared it (a display label). */
+    ownerLabel: string;
+    /** The grantId - pass it back as `from` to READ that share. */
+    grantId: string;
+}
+/** The result of a `shared_context` call. */
+interface SharedContextResult {
+    /** `"list"` when called with no `from`, `"read"` when a `from` was given. */
+    mode: "list" | "read";
+    /** LIST mode: the available shares (metadata only). */
+    shares: SharedContextEntry[];
+    /** READ mode: the selected composite text, or null when not available. */
+    composite: string | null;
+    /** The full rendered text the membrane returned. */
+    text: string;
+}
+/** Options accepted by `ask`. */
+interface AskOptions {
+    /** How many passages to return (default 12, max 50). */
+    k?: number;
+    /** Bound an `"all"`-token call to one of your projects (server-validated). */
+    projectId?: string;
+}
+/** A pluggable transport so the client is testable with zero real network. */
+interface Transport {
+    /**
+     * POST one JSON-RPC request to the membrane `/mcp` endpoint with the given
+     * bearer token. Returns the parsed HTTP status + JSON body. The default
+     * transport is `fetch`-based; tests inject a mock.
+     */
+    (req: {
+        url: string;
+        token: string;
+        body: unknown;
+    }): Promise<TransportResponse>;
+}
+/** What a transport hands back: the HTTP status, parsed body, and 401 header. */
+interface TransportResponse {
+    status: number;
+    /** The parsed JSON body (or null on a non-JSON / empty body). */
+    body: unknown;
+    /** The `WWW-Authenticate` header value, when the server sent one (401s). */
+    wwwAuthenticate?: string | null;
+}
+/** Pluggable storage so token persistence is testable + SSR-safe. */
+interface StorageAdapter {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+/** Options for `useMyContext()` / `createClient()`. */
+interface ClientOptions {
+    /** The membrane MCP endpoint. Defaults to the production URL. */
+    endpoint?: string;
+    /** A custom transport (tests inject a mock; defaults to `fetch`). */
+    transport?: Transport;
+    /**
+     * Where to persist the token across reloads. Defaults to `localStorage` when
+     * available, else an in-memory store (SSR-safe). Pass `null` to disable
+     * persistence entirely.
+     */
+    storage?: StorageAdapter | null;
+    /** The storage key under which the token is persisted. */
+    storageKey?: string;
+    /** Called whenever the connect state changes (the React hook uses this). */
+    onStateChange?: (state: ConnectState) => void;
+}
+/** The arguments to `connect()` - v1 is TOKEN-IN ONLY. */
+interface ConnectArgs {
+    /** A UseMyContext session token (the user's own bearer, as Claude holds). */
+    token: string;
+}
+
+/** The production membrane MCP endpoint. */
+declare const DEFAULT_ENDPOINT = "https://mcp.usemycontext.ai/mcp";
+/** The shape `useMyContext()` returns - the client handle. */
+interface UseMyContextClient {
+    /** The current connect state. */
+    readonly state: ConnectState;
+    /** Convenience: true iff `state === "connected"`. */
+    readonly connected: boolean;
+    /** The held token, when connected (else null). */
+    readonly token: string | null;
+    /** Subscribe to state changes. Returns an unsubscribe fn. */
+    subscribe(listener: (state: ConnectState) => void): () => void;
+    /** v1 TOKEN-IN connect: validate the token against the membrane. */
+    connect(args: ConnectArgs): Promise<ConnectState>;
+    /** Clear the token + persisted storage; -> `disconnected`. */
+    disconnect(): void;
+    profile(): Promise<ProfileResult>;
+    listFiles(): Promise<FileMeta[]>;
+    searchFiles(query: string): Promise<FileMeta[]>;
+    getFile(fileId: string): Promise<GetFileResult>;
+    ask(query: string, opts?: AskOptions): Promise<AskResult>;
+    suggestUpdate(suggestion: string): Promise<SuggestUpdateResult>;
+    sharedContext(from?: string): Promise<SharedContextResult>;
+}
+/**
+ * Create a UseMyContext client. Framework-free: the React hook wraps this.
+ * Restores a persisted token (without revalidating) so a returning host page
+ * starts `connected`; a stale token surfaces as `expired` on the first call.
+ */
+declare function useMyContext(options?: ClientOptions): UseMyContextClient;
+/** Thrown for a bad SDK call argument (a developer error, not a state event). */
+declare class UseMyContextConnectArgError extends UseMyContextError {
+    constructor(message?: string);
+}
+
+export { type AskOptions as A, type ClientOptions as C, DEFAULT_ENDPOINT as D, type FileMeta as F, type GetFileResult as G, NotConnectedError as N, type ProfileResult as P, ScopeDeniedError as S, TokenExpiredError as T, type UseMyContextClient as U, type AskPassage as a, type AskResult as b, type ConnectArgs as c, type ConnectState as d, type SharedContextEntry as e, type SharedContextResult as f, type StorageAdapter as g, type SuggestUpdateResult as h, ToolCallError as i, type Transport as j, TransportError as k, type TransportResponse as l, UseMyContextConnectArgError as m, UseMyContextError as n, useMyContext as u };

package/dist/client-mXQsH2mZ.d.ts

@@ -0,0 +1,217 @@
+/** Base class for every error the SDK throws, so callers can `catch (e)`. */
+declare class UseMyContextError extends Error {
+    constructor(message: string);
+}
+/** Thrown when a tool wrapper is called before a successful `connect()`. */
+declare class NotConnectedError extends UseMyContextError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the membrane rejects the token (HTTP 401 + WWW-Authenticate).
+ * The client also transitions to `expired` so the host can re-connect.
+ */
+declare class TokenExpiredError extends UseMyContextError {
+    /** The raw `WWW-Authenticate` header, when the server sent one. */
+    readonly wwwAuthenticate?: string;
+    constructor(message?: string, wwwAuthenticate?: string);
+}
+/** Thrown when a tool call is refused for lack of scope (membrane -32604). */
+declare class ScopeDeniedError extends UseMyContextError {
+    readonly code = -32604;
+    constructor(message: string);
+}
+/** Thrown for a JSON-RPC protocol error or a tool-level `isError` result. */
+declare class ToolCallError extends UseMyContextError {
+    /** The JSON-RPC error code, when the failure was a protocol error. */
+    readonly code?: number;
+    constructor(message: string, code?: number);
+}
+/** Thrown for transport/parse failures (network down, non-JSON body, ...). */
+declare class TransportError extends UseMyContextError {
+    constructor(message: string);
+}
+
+/**
+ * The connect state machine the hook/client exposes.
+ *
+ *  - `idle`         nothing attempted yet (the fresh client).
+ *  - `connecting`   `connect({token})` is validating the token against the
+ *                   membrane (an `initialize` round-trip).
+ *  - `connected`    a valid token is held; the 7 tool wrappers are callable.
+ *  - `declined`     the user/host explicitly refused the connection (reserved
+ *                   for the v2 OAuth popup path; a v1 token-in connect never
+ *                   enters it on its own, but the reducer models it).
+ *  - `expired`      a previously-`connected` token was rejected by the membrane
+ *                   (a 401 + WWW-Authenticate); the host should re-connect.
+ *  - `error`        a non-auth failure (network/transport/parse) ended a connect
+ *                   or a wrapper call.
+ *  - `disconnected` `disconnect()` was called; the token is cleared.
+ */
+type ConnectState = "idle" | "connecting" | "connected" | "declined" | "expired" | "error" | "disconnected";
+/** One file's metadata as returned by `list_files` / `search_files`. */
+interface FileMeta {
+    id: string;
+    name: string;
+    size: number;
+    contentType: string;
+    modified: string;
+    /** Owner-side processing status; may be absent on legacy shapes. */
+    status?: "not-processed" | "processing" | "available" | "error";
+}
+/** The compiled personal context the `profile` tool serves. */
+interface ProfileResult {
+    /**
+     * The compiled composite text, ready to drop into a system prompt. When the
+     * user has no compiled context yet, the membrane falls back to raw facts and
+     * this is the JSON of `{ facts: [...] }` rendered as text - in that case
+     * `facts` is populated and `composite` is the same string.
+     */
+    composite: string;
+    /** Raw facts, present only when the membrane fell back (no compile yet). */
+    facts?: string[];
+}
+/** One cited passage returned by `ask_docs`. */
+interface AskPassage {
+    /** 1-based citation index as rendered by the membrane. */
+    index: number;
+    /** The passage text the LLM should reason over and quote. */
+    text: string;
+    /** The source file the passage was cited from (when present). */
+    file?: string;
+    /** The access scope (the owning user id) as cited. */
+    scope?: string;
+    /** The retrieval score (higher = more relevant), when present. */
+    score?: number;
+}
+/** The result of an `ask_docs` call. */
+interface AskResult {
+    /** The cited passages, in rank order. Empty when nothing matched. */
+    passages: AskPassage[];
+    /** The raw rendered text the membrane returned (citations + passages). */
+    text: string;
+}
+/** The result of a `get_file` call. */
+interface GetFileResult {
+    /** The full rendered text the membrane returned for the file. */
+    text: string;
+    /** A short-lived download link, parsed out of the rendered text when present. */
+    downloadUrl?: string;
+}
+/** The result of a `suggest_update` call (the one write tool). */
+interface SuggestUpdateResult {
+    /** The candidate id the membrane assigned, when it could be parsed. */
+    id?: string;
+    /** The full rendered acknowledgement text. */
+    text: string;
+}
+/** One share listed by `shared_context` (LIST mode). */
+interface SharedContextEntry {
+    /** Who shared it (a display label). */
+    ownerLabel: string;
+    /** The grantId - pass it back as `from` to READ that share. */
+    grantId: string;
+}
+/** The result of a `shared_context` call. */
+interface SharedContextResult {
+    /** `"list"` when called with no `from`, `"read"` when a `from` was given. */
+    mode: "list" | "read";
+    /** LIST mode: the available shares (metadata only). */
+    shares: SharedContextEntry[];
+    /** READ mode: the selected composite text, or null when not available. */
+    composite: string | null;
+    /** The full rendered text the membrane returned. */
+    text: string;
+}
+/** Options accepted by `ask`. */
+interface AskOptions {
+    /** How many passages to return (default 12, max 50). */
+    k?: number;
+    /** Bound an `"all"`-token call to one of your projects (server-validated). */
+    projectId?: string;
+}
+/** A pluggable transport so the client is testable with zero real network. */
+interface Transport {
+    /**
+     * POST one JSON-RPC request to the membrane `/mcp` endpoint with the given
+     * bearer token. Returns the parsed HTTP status + JSON body. The default
+     * transport is `fetch`-based; tests inject a mock.
+     */
+    (req: {
+        url: string;
+        token: string;
+        body: unknown;
+    }): Promise<TransportResponse>;
+}
+/** What a transport hands back: the HTTP status, parsed body, and 401 header. */
+interface TransportResponse {
+    status: number;
+    /** The parsed JSON body (or null on a non-JSON / empty body). */
+    body: unknown;
+    /** The `WWW-Authenticate` header value, when the server sent one (401s). */
+    wwwAuthenticate?: string | null;
+}
+/** Pluggable storage so token persistence is testable + SSR-safe. */
+interface StorageAdapter {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+/** Options for `useMyContext()` / `createClient()`. */
+interface ClientOptions {
+    /** The membrane MCP endpoint. Defaults to the production URL. */
+    endpoint?: string;
+    /** A custom transport (tests inject a mock; defaults to `fetch`). */
+    transport?: Transport;
+    /**
+     * Where to persist the token across reloads. Defaults to `localStorage` when
+     * available, else an in-memory store (SSR-safe). Pass `null` to disable
+     * persistence entirely.
+     */
+    storage?: StorageAdapter | null;
+    /** The storage key under which the token is persisted. */
+    storageKey?: string;
+    /** Called whenever the connect state changes (the React hook uses this). */
+    onStateChange?: (state: ConnectState) => void;
+}
+/** The arguments to `connect()` - v1 is TOKEN-IN ONLY. */
+interface ConnectArgs {
+    /** A UseMyContext session token (the user's own bearer, as Claude holds). */
+    token: string;
+}
+
+/** The production membrane MCP endpoint. */
+declare const DEFAULT_ENDPOINT = "https://mcp.usemycontext.ai/mcp";
+/** The shape `useMyContext()` returns - the client handle. */
+interface UseMyContextClient {
+    /** The current connect state. */
+    readonly state: ConnectState;
+    /** Convenience: true iff `state === "connected"`. */
+    readonly connected: boolean;
+    /** The held token, when connected (else null). */
+    readonly token: string | null;
+    /** Subscribe to state changes. Returns an unsubscribe fn. */
+    subscribe(listener: (state: ConnectState) => void): () => void;
+    /** v1 TOKEN-IN connect: validate the token against the membrane. */
+    connect(args: ConnectArgs): Promise<ConnectState>;
+    /** Clear the token + persisted storage; -> `disconnected`. */
+    disconnect(): void;
+    profile(): Promise<ProfileResult>;
+    listFiles(): Promise<FileMeta[]>;
+    searchFiles(query: string): Promise<FileMeta[]>;
+    getFile(fileId: string): Promise<GetFileResult>;
+    ask(query: string, opts?: AskOptions): Promise<AskResult>;
+    suggestUpdate(suggestion: string): Promise<SuggestUpdateResult>;
+    sharedContext(from?: string): Promise<SharedContextResult>;
+}
+/**
+ * Create a UseMyContext client. Framework-free: the React hook wraps this.
+ * Restores a persisted token (without revalidating) so a returning host page
+ * starts `connected`; a stale token surfaces as `expired` on the first call.
+ */
+declare function useMyContext(options?: ClientOptions): UseMyContextClient;
+/** Thrown for a bad SDK call argument (a developer error, not a state event). */
+declare class UseMyContextConnectArgError extends UseMyContextError {
+    constructor(message?: string);
+}
+
+export { type AskOptions as A, type ClientOptions as C, DEFAULT_ENDPOINT as D, type FileMeta as F, type GetFileResult as G, NotConnectedError as N, type ProfileResult as P, ScopeDeniedError as S, TokenExpiredError as T, type UseMyContextClient as U, type AskPassage as a, type AskResult as b, type ConnectArgs as c, type ConnectState as d, type SharedContextEntry as e, type SharedContextResult as f, type StorageAdapter as g, type SuggestUpdateResult as h, ToolCallError as i, type Transport as j, TransportError as k, type TransportResponse as l, UseMyContextConnectArgError as m, UseMyContextError as n, useMyContext as u };