mcpscraper-memory-sdk 0.2.0

package/README.md

@@ -0,0 +1,51 @@
+# mcpscraper-memory-sdk
+
+Official TypeScript/JavaScript client for [memory.mcpscraper.dev](https://memory.mcpscraper.dev) — a hosted, per-user, multi-vault memory API (notes, search, tables, channels, scheduled actions, and more).
+
+This is a thin client: every method sends a JSON-RPC 2.0 `tools/call` request to `/mcp` with your Bearer API key and parses the response. No memory/vault logic lives in this package — see [`contracts/memory.tools.json`](../../contracts/memory.tools.json) for the full contract this client is generated from.
+
+## Install
+
+```bash
+npm install mcpscraper-memory-sdk
+```
+
+## Quickstart
+
+```ts
+import { MemoryClient, MemoryApiError } from 'mcpscraper-memory-sdk'
+
+const client = new MemoryClient({ apiKey: process.env.MCP_MEMORY_API_KEY! })
+
+try {
+  const results = await client.memory.search({ query: 'q3 roadmap decisions' })
+  console.log(results.results)
+
+  const note = await client.memory.get({ path: 'projects/q3-plan' })
+  console.log(note)
+} catch (err) {
+  if (err instanceof MemoryApiError) {
+    console.error('memory API error:', err.message, err.rpcCode, err.httpStatus)
+  } else {
+    throw err
+  }
+}
+```
+
+## Namespaces
+
+Methods are grouped by category, matching [`contracts/memory.tools.json`](../../contracts/memory.tools.json): `client.memory` (get/list/put/search/suggest/export/upload/deleteNote), `client.vaults`, `client.access` (keys, shares, invites), `client.channels`, `client.tables`, `client.schedule`, `client.webhooks`, `client.facts`, `client.recall`, `client.storage`, `client.video`, `client.library`, `client.capture`.
+
+Every method's input/output types are generated from the live tool schemas (see `src/generated/`, produced by `npm run generate` at the repo root from `contracts/memory.tools.json`) — no hand-maintained duplicate types to drift out of sync.
+
+## Getting an API key
+
+Issue one via the `access-issue-key` tool (or `client.access.issueKey(...)` once you have an initial key), or through the memory dashboard.
+
+## Errors
+
+All failures — HTTP-level, JSON-RPC-level, and MCP tool-level (`isError: true`) — surface as a single `MemoryApiError` with `httpStatus`, `rpcCode`, and `data`/`toolError` fields depending on where the failure occurred.
+
+## See also
+
+[Repo README](../../README.md) (multi-language examples with real sample output) · [`mcpscraper-sdk`](../scraper) (Node, also reaches these 85 tools via `client.memoryTools` using only a scraper key) · [`mcpscraper-memory-sdk` on PyPI](../memory-python) (Python) · [`mcpscraper-cli`](../cli)

package/dist/index.cjs

@@ -0,0 +1,510 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AccessNamespace: () => AccessNamespace,
+  CaptureNamespace: () => CaptureNamespace,
+  ChannelsNamespace: () => ChannelsNamespace,
+  FactsNamespace: () => FactsNamespace,
+  GraphNamespace: () => GraphNamespace,
+  LibraryNamespace: () => LibraryNamespace,
+  MemoryApiError: () => MemoryApiError,
+  MemoryClient: () => MemoryClient,
+  MemoryNamespace: () => MemoryNamespace,
+  RecallNamespace: () => RecallNamespace,
+  ScheduleNamespace: () => ScheduleNamespace,
+  StorageNamespace: () => StorageNamespace,
+  TablesNamespace: () => TablesNamespace,
+  TagsNamespace: () => TagsNamespace,
+  VaultsNamespace: () => VaultsNamespace,
+  VideoNamespace: () => VideoNamespace,
+  WebhooksNamespace: () => WebhooksNamespace
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var MemoryApiError = class extends Error {
+  httpStatus;
+  rpcCode;
+  data;
+  toolError;
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "MemoryApiError";
+    this.httpStatus = details.httpStatus;
+    this.rpcCode = details.rpcCode;
+    this.data = details.data;
+    this.toolError = details.toolError;
+  }
+};
+
+// src/generated/methods.ts
+var AccessNamespace = class {
+  constructor(callTool) {
+    this.callTool = callTool;
+  }
+  callTool;
+  async issueKey(input) {
+    return this.callTool("issueKeyTool", input);
+  }
+  async listKeys(input) {
+    return this.callTool("listKeysTool", input);
+  }
+  async revokeKey(input) {
+    return this.callTool("revokeKeyTool", input);
+  }
+  async setScope(input) {
+    return this.callTool("setScopeTool", input);
+  }
+  async shareVault(input) {
+    return this.callTool("shareVaultTool", input);
+  }
+  async swapVault(input) {
+    return this.callTool("swapVaultTool", input);
+  }
+  async inviteAccount(input) {
+    return this.callTool("inviteAccountTool", input);
+  }
+  async switchAccount(input) {
+    return this.callTool("switchAccountTool", input);
+  }
+  async approveSender(input) {
+    return this.callTool("approveSenderTool", input);
+  }
+  async removeApprovedSender(input) {
+    return this.callTool("removeApprovedSenderTool", input);
+  }
+  async listApprovedSenders(input) {
+    return this.callTool("listApprovedSendersTool", input);
+  }
+  async inboxSettings(input) {
+    return this.callTool("inboxSettingsTool", input);
+  }
+  async shareNote(input) {
+    return this.callTool("shareNoteTool", input);
+  }
+  async noteInbox(input) {
+    return this.callTool("noteInboxTool", input);
+  }
+  async acceptShare(input) {
+    return this.callTool("acceptShareTool", input);
+  }
+  async declineShare(input) {
+    return this.callTool("declineShareTool", input);
+  }
+  async unlinkShare(input) {
+    return this.callTool("unlinkShareTool", input);
+  }
+  async revokeShare(input) {
+    return this.callTool("revokeShareTool", input);
+  }
+  async getChatLink(input) {
+    return this.callTool("getChatLinkTool", input);
+  }
+  async revokeChatLink(input) {
+    return this.callTool("revokeChatLinkTool", input);
+  }
+  async setAgentIdentity(input) {
+    return this.callTool("setAgentIdentityTool", input);
+  }
+};
+var VaultsNamespace = class {
+  constructor(callTool) {
+    this.callTool = callTool;
+  }
+  callTool;
+  async listSharedWithMe(input) {
+    return this.callTool("listSharedWithMeTool", input);
+  }
+  async listVaults(input) {
+    return this.callTool("listVaultsTool", input);
+  }
+  async addVault(input) {
+    return this.callTool("addVaultTool", input);
+  }
+  async createSecureVault(input) {
+    return this.callTool("createSecureVaultTool", input);
+  }
+  async deleteVault(input) {
+    return this.callTool("deleteVaultTool", input);
+  }
+  async provisionDefaults(input) {
+    return this.callTool("provisionDefaultsTool", input);
+  }
+  async getVaultContract(input) {
+    return this.callTool("getVaultContractTool", input);
+  }
+  async routeMemory(input) {
+    return this.callTool("routeMemoryTool", input);
+  }
+};
+var ChannelsNamespace = class {
+  constructor(callTool) {
+    this.callTool = callTool;
+  }
+  callTool;
+  async createChannel(input) {
+    return this.callTool("createChannelTool", input);
+  }
+  async postMessage(input) {
+    return this.callTool("postMessageTool", input);
+  }
+  async replyMessage(input) {
+    return this.callTool("replyMessageTool", input);
+  }
+  async listChannelMessages(input) {
+    return this.callTool("listChannelMessagesTool", input);
+  }
+  async reactMessage(input) {
+    return this.callTool("reactMessageTool", input);
+  }
+  async myMentions(input) {
+    return this.callTool("myMentionsTool", input);
+  }
+  async listChannelMembers(input) {
+    return this.callTool("listChannelMembersTool", input);
+  }
+  async removeChannelMember(input) {
+    return this.callTool("removeChannelMemberTool", input);
+  }
+  async pollChannel(input) {
+    return this.callTool("pollChannelTool", input);
+  }
+  async getMessageNote(input) {
+    return this.callTool("getMessageNoteTool", input);
+  }
+};
+var CaptureNamespace = class {
+  constructor(callTool) {
+    this.callTool = callTool;
+  }
+  callTool;
+  async memoryQuestions(input) {
+    return this.callTool("memoryQuestionsTool", input);
+  }
+  async prepareMemoryWrite(input) {
+    return this.callTool("prepareMemoryWriteTool", input);
+  }
+  async validateMemoryWrite(input) {
+    return this.callTool("validateMemoryWriteTool", input);
+  }
+  async memoryCapture(input) {
+    return this.callTool("memoryCaptureTool", input);
+  }
+};
+var LibraryNamespace = class {
+  constructor(callTool) {
+    this.callTool = callTool;
+  }
+  callTool;
+  async ingest(input) {
+    return this.callTool("libraryIngestTool", input);
+  }
+};
+var MemoryNamespace = class {
+  constructor(callTool) {
+    this.callTool = callTool;
+  }
+  callTool;
+  async export(input) {
+    return this.callTool("exportTool", input);
+  }
+  async get(input) {
+    return this.callTool("getTool", input);
+  }
+  async list(input) {
+    return this.callTool("listTool", input);
+  }
+  async put(input) {
+    return this.callTool("putTool", input);
+  }
+  async search(input) {
+    return this.callTool("searchTool", input);
+  }
+  async suggest(input) {
+    return this.callTool("suggestTool", input);
+  }
+  async upload(input) {
+    return this.callTool("uploadTool", input);
+  }
+  async deleteNote(input) {
+    return this.callTool("deleteNoteTool", input);
+  }
+};
+var TablesNamespace = class {
+  constructor(callTool) {
+    this.callTool = callTool;
+  }
+  callTool;
+  async create(input) {
+    return this.callTool("createTableTool", input);
+  }
+  async list(input) {
+    return this.callTool("listTablesTool", input);
+  }
+  async describe(input) {
+    return this.callTool("describeTableTool", input);
+  }
+  async insertRows(input) {
+    return this.callTool("insertTableRowsTool", input);
+  }
+  async query(input) {
+    return this.callTool("queryTableTool", input);
+  }
+  async deleteRows(input) {
+    return this.callTool("deleteTableRowsTool", input);
+  }
+  async drop(input) {
+    return this.callTool("dropTableTool", input);
+  }
+};
+var RecallNamespace = class {
+  constructor(callTool) {
+    this.callTool = callTool;
+  }
+  callTool;
+  async temporalRecall(input) {
+    return this.callTool("temporalRecallTool", input);
+  }
+};
+var TagsNamespace = class {
+  constructor(callTool) {
+    this.callTool = callTool;
+  }
+  callTool;
+  async listMemoryTags(input) {
+    return this.callTool("listTagsTool", input);
+  }
+  async resolveMemoryTags(input) {
+    return this.callTool("resolveTagsTool", input);
+  }
+  async upsertMemoryTag(input) {
+    return this.callTool("upsertTagTool", input);
+  }
+};
+var GraphNamespace = class {
+  constructor(callTool) {
+    this.callTool = callTool;
+  }
+  callTool;
+  async memoryBacklinks(input) {
+    return this.callTool("noteBacklinksTool", input);
+  }
+  async memoryGraphUniverse(input) {
+    return this.callTool("graphUniverseTool", input);
+  }
+  async memoryGraphPath(input) {
+    return this.callTool("graphPathTool", input);
+  }
+};
+var FactsNamespace = class {
+  constructor(callTool) {
+    this.callTool = callTool;
+  }
+  callTool;
+  async recordFact(input) {
+    return this.callTool("recordFactTool", input);
+  }
+  async history(input) {
+    return this.callTool("factHistoryTool", input);
+  }
+};
+var StorageNamespace = class {
+  constructor(callTool) {
+    this.callTool = callTool;
+  }
+  callTool;
+  async usage(input) {
+    return this.callTool("storageUsageTool", input);
+  }
+  async costUsage(input) {
+    return this.callTool("costUsageTool", input);
+  }
+};
+var ScheduleNamespace = class {
+  constructor(callTool) {
+    this.callTool = callTool;
+  }
+  callTool;
+  async createScheduledAction(input) {
+    return this.callTool("createScheduledActionTool", input);
+  }
+  async listScheduledActions(input) {
+    return this.callTool("listScheduledActionsTool", input);
+  }
+  async pauseScheduledAction(input) {
+    return this.callTool("pauseScheduledActionTool", input);
+  }
+  async resumeScheduledAction(input) {
+    return this.callTool("resumeScheduledActionTool", input);
+  }
+  async deleteScheduledAction(input) {
+    return this.callTool("deleteScheduledActionTool", input);
+  }
+  async setScheduleEntitlement(input) {
+    return this.callTool("setScheduleEntitlementTool", input);
+  }
+  async getScheduleStatus(input) {
+    return this.callTool("getScheduleStatusTool", input);
+  }
+  async proposeScheduledAction(input) {
+    return this.callTool("proposeScheduledActionTool", input);
+  }
+  async getScheduleLink(input) {
+    return this.callTool("getScheduleLinkTool", input);
+  }
+  async revokeScheduleLink(input) {
+    return this.callTool("revokeScheduleLinkTool", input);
+  }
+};
+var WebhooksNamespace = class {
+  constructor(callTool) {
+    this.callTool = callTool;
+  }
+  callTool;
+  async createWebhook(input) {
+    return this.callTool("createWebhookTool", input);
+  }
+  async listWebhooks(input) {
+    return this.callTool("listWebhooksTool", input);
+  }
+  async revokeWebhook(input) {
+    return this.callTool("revokeWebhookTool", input);
+  }
+};
+var VideoNamespace = class {
+  constructor(callTool) {
+    this.callTool = callTool;
+  }
+  callTool;
+  async analyzeStart(input) {
+    return this.callTool("videoAnalyzeStartTool", input);
+  }
+  async analyzeStatus(input) {
+    return this.callTool("videoAnalyzeStatusTool", input);
+  }
+};
+
+// src/client.ts
+var MemoryClient = class {
+  access;
+  capture;
+  channels;
+  facts;
+  graph;
+  library;
+  memory;
+  recall;
+  schedule;
+  storage;
+  tables;
+  tags;
+  vaults;
+  video;
+  webhooks;
+  apiKey;
+  baseUrl;
+  fetchImpl;
+  rpcId = 0;
+  constructor(options) {
+    this.apiKey = options.apiKey;
+    this.baseUrl = options.baseUrl ?? "https://memory.mcpscraper.dev";
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    const callTool = this.callTool.bind(this);
+    this.access = new AccessNamespace(callTool);
+    this.capture = new CaptureNamespace(callTool);
+    this.channels = new ChannelsNamespace(callTool);
+    this.facts = new FactsNamespace(callTool);
+    this.graph = new GraphNamespace(callTool);
+    this.library = new LibraryNamespace(callTool);
+    this.memory = new MemoryNamespace(callTool);
+    this.recall = new RecallNamespace(callTool);
+    this.schedule = new ScheduleNamespace(callTool);
+    this.storage = new StorageNamespace(callTool);
+    this.tables = new TablesNamespace(callTool);
+    this.tags = new TagsNamespace(callTool);
+    this.vaults = new VaultsNamespace(callTool);
+    this.video = new VideoNamespace(callTool);
+    this.webhooks = new WebhooksNamespace(callTool);
+  }
+  async callTool(name, args) {
+    const res = await this.fetchImpl(`${this.baseUrl}/mcp`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream",
+        authorization: `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: ++this.rpcId,
+        method: "tools/call",
+        params: { name, arguments: args }
+      })
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => void 0);
+      throw new MemoryApiError(`HTTP ${res.status} calling tool "${name}"`, { httpStatus: res.status, data: body });
+    }
+    const payload = await res.json();
+    if (payload.error) {
+      throw new MemoryApiError(payload.error.message, { rpcCode: payload.error.code, data: payload.error.data });
+    }
+    const result = payload.result;
+    const textBlock = result?.content?.find((block) => block.type === "text")?.text;
+    let parsed = textBlock;
+    if (typeof textBlock === "string") {
+      try {
+        parsed = JSON.parse(textBlock);
+      } catch {
+        parsed = textBlock;
+      }
+    }
+    if (result?.structuredContent !== void 0) {
+      parsed = result.structuredContent;
+    }
+    if (result?.isError) {
+      const message = parsed && typeof parsed === "object" && "message" in parsed ? String(parsed.message) : typeof parsed === "string" ? parsed : `Tool "${name}" failed`;
+      throw new MemoryApiError(message, { toolError: parsed });
+    }
+    return parsed;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AccessNamespace,
+  CaptureNamespace,
+  ChannelsNamespace,
+  FactsNamespace,
+  GraphNamespace,
+  LibraryNamespace,
+  MemoryApiError,
+  MemoryClient,
+  MemoryNamespace,
+  RecallNamespace,
+  ScheduleNamespace,
+  StorageNamespace,
+  TablesNamespace,
+  TagsNamespace,
+  VaultsNamespace,
+  VideoNamespace,
+  WebhooksNamespace
+});