@persistmemory/sdk 0.1.2 → 0.3.0

package/dist/client.d.ts

@@ -5,6 +5,7 @@ import { Spaces } from "./resources/spaces.js";
 import { Documents, Jobs, Sources } from "./resources/ingestion.js";
 import { Conflicts, Entities, Graph } from "./resources/knowledge.js";
 import { Conversations } from "./resources/conversations.js";
+import { Google } from "./resources/google.js";
 import { Integrations } from "./resources/integrations.js";
 import { Health } from "./resources/health.js";
 import { Agent } from "./resources/agent.js";
@@ -32,6 +33,8 @@ export declare class PersistMemory {
     readonly conflicts: Conflicts;
     readonly conversations: Conversations;
     readonly integrations: Integrations;
+    /** Drive, mail and contacts on the user's connected Google account. */
+    readonly google: Google;
     readonly health: Health;
     readonly agent: Agent;
     constructor(options: ClientOptions);

package/dist/http.d.ts

@@ -64,6 +64,18 @@ interface InternalRequest {
     readonly path: string;
     readonly query?: QueryParams;
     readonly body?: unknown;
+    /**
+     * Bytes, for the endpoints that take a file.
+     *
+     * Separate from `body` rather than sniffed out of it: `JSON.stringify` of a
+     * `Uint8Array` produces `{"0":137,"1":80,...}`, which is a valid request and
+     * a corrupt file - and the failure shows up as "this PDF is not a PDF" a
+     * long way from the line that caused it.
+     */
+    readonly rawBody?: Uint8Array;
+    readonly contentType?: string;
+    /** Bytes back, for a download. JSON is parsed; a file is not. */
+    readonly rawResponse?: boolean;
     readonly options?: RequestOptions;
 }
 export declare class HttpClient {
@@ -80,6 +92,14 @@ export declare class HttpClient {
     toJSON(): Record<string, unknown>;
     get<T>(path: string, query?: QueryParams, options?: RequestOptions): Promise<T>;
     post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /** POST with a file as the body. The type describes the bytes, not JSON. */
+    postBytes<T>(path: string, bytes: Uint8Array, contentType: string, query?: QueryParams, options?: RequestOptions): Promise<T>;
+    /** GET that returns bytes rather than JSON, for downloading a file. */
+    getBytes(path: string, query?: QueryParams, options?: RequestOptions): Promise<{
+        bytes: Uint8Array;
+        contentType: string;
+        filename?: string;
+    }>;
     patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
     delete<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
 }

package/dist/index.cjs

@@ -279,6 +279,27 @@ var HttpClient = class {
       ...options ? { options } : {}
     });
   }
+  /** POST with a file as the body. The type describes the bytes, not JSON. */
+  async postBytes(path, bytes, contentType, query, options) {
+    return this.#request({
+      method: "POST",
+      path,
+      rawBody: bytes,
+      contentType,
+      ...query ? { query } : {},
+      ...options ? { options } : {}
+    });
+  }
+  /** GET that returns bytes rather than JSON, for downloading a file. */
+  async getBytes(path, query, options) {
+    return this.#request({
+      method: "GET",
+      path,
+      rawResponse: true,
+      ...query ? { query } : {},
+      ...options ? { options } : {}
+    });
+  }
   async patch(path, body, options) {
     return this.#request({
       method: "PATCH",
@@ -331,11 +352,20 @@ var HttpClient = class {
         this.#fetch(url, {
           method: request.method,
           headers: this.#headers(request),
-          ...request.body !== void 0 ? { body: JSON.stringify(request.body) } : {},
+          ...request.rawBody !== void 0 ? { body: request.rawBody } : request.body !== void 0 ? { body: JSON.stringify(request.body) } : {},
           signal: deadline.signal
         }),
         deadline.signal
       );
+      if (request.rawResponse && response.ok) {
+        const disposition = response.headers.get("content-disposition") ?? "";
+        const named = /filename="([^"]+)"/.exec(disposition)?.[1];
+        return {
+          bytes: new Uint8Array(await response.arrayBuffer()),
+          contentType: response.headers.get("content-type") ?? "application/octet-stream",
+          ...named ? { filename: named } : {}
+        };
+      }
       const payload = await readBody(response);
       if (!response.ok) throw errorFromResponse(response.status, payload, response.headers);
       return payload;
@@ -356,9 +386,11 @@ var HttpClient = class {
     return {
       // The only place the key is ever read.
       authorization: `Bearer ${this.#apiKey}`,
-      accept: "application/json",
+      // A download route answers with the file's own type, so `*/*` rather
+      // than a promise to accept only JSON that the server would have to break.
+      accept: request.rawResponse ? "*/*" : "application/json",
       "user-agent": this.#userAgent,
-      ...request.body !== void 0 ? { "content-type": "application/json" } : {},
+      ...request.rawBody !== void 0 ? { "content-type": request.contentType ?? "application/octet-stream" } : request.body !== void 0 ? { "content-type": "application/json" } : {},
       ...request.options?.idempotencyKey ? { "idempotency-key": request.options.idempotencyKey } : {}
     };
   }
@@ -670,17 +702,22 @@ var Spaces = class {
   /**
    * The memories filed in a Space.
    *
-   * This endpoint answers `{ data, pagination: { limit } }` with no cursor: it
-   * returns the first `limit` members and stops. Wrapped in a `Paginated`
-   * anyway so it reads like every other list, and it simply yields one page -
-   * a caller who needs more should filter `memories.list` by `spaceIds`, which
-   * is the endpoint that actually pages.
+   * The cursor is PASSED. This fetch used to ignore the paginator's cursor
+   * on the stale belief that the endpoint had none — the server has minted
+   * `pagination.nextCursor` since it started paging, and its own comment
+   * says "both SDKs iterate by reading pagination". Ignoring it meant every
+   * page request was identical: the loop guard saw a non-advancing fetch and
+   * stopped silently, so `all()` returned the first page twice and dropped
+   * everything after it — duplicated AND truncated data, with no error.
    */
   memories(id, params = {}, options) {
     return new Paginated(
-      () => this.#http.get(
+      (cursor) => this.#http.get(
         `/api/v1/spaces/${encodeURIComponent(id)}/memories`,
-        { ...params.limit !== void 0 ? { limit: params.limit } : {} },
+        {
+          ...params.limit !== void 0 ? { limit: params.limit } : {},
+          ...cursor !== void 0 ? { cursor } : {}
+        },
         options
       )
     );
@@ -706,6 +743,94 @@ var Spaces = class {
       options
     );
   }
+  /* ----------------------- who else can see it ----------------------- */
+  /**
+   * Who can see this Space, including invitations nobody has accepted.
+   *
+   * A DIFFERENT EDGE from `memories()` next door, and the difference is worth
+   * holding on to: that one maps a MEMORY to a Space, this one maps a PERSON
+   * to a Space. The server keeps them in two tables with two names for exactly
+   * that reason.
+   *
+   * Read `acceptedAt` before you render a row. An invitation grants nothing
+   * until it is accepted, so a list that draws invited and accepted people the
+   * same way tells its user somebody is reading their memories when nobody is.
+   *
+   * Paginated like every other list here. A Space has a handful of
+   * collaborators rather than thousands, so this will usually be one page -
+   * which costs a caller nothing and means the shape does not change if a
+   * Space ever has an organisation on it.
+   */
+  collaborators(id, params = {}, options) {
+    return new Paginated(
+      (cursor) => this.#http.get(
+        `/api/v1/sharing/spaces/${encodeURIComponent(id)}/collaborators`,
+        {
+          ...params.limit !== void 0 ? { limit: params.limit } : {},
+          ...cursor !== void 0 ? { cursor } : {}
+        },
+        options
+      )
+    );
+  }
+  /**
+   * Offers somebody sight of a Space. Answers with the invitation.
+   *
+   * AN OFFER, NOT A GRANT, and the returned `acceptedAt` will be absent to
+   * prove it. The recipient has to accept before they can see anything, which
+   * is the property that keeps "nothing enters your memory without you" true
+   * even when somebody else starts the sharing. Do not tell your user their
+   * Space "has been shared" on the strength of a 2xx here.
+   *
+   * WHAT THEY GET IS THE WHOLE SPACE: every memory already filed in it and
+   * every memory that lands in it afterwards. There is no narrower grant, and
+   * `role` does not make one - it decides what they may do BESIDES read.
+   *
+   * Worth an idempotency key when a person is behind it. A double-clicked
+   * "share" is two invitations to the same address, and the second one is a
+   * second email arriving at somebody who has already been asked.
+   */
+  async share(id, params, options) {
+    return this.#http.post(
+      `/api/v1/sharing/spaces/${encodeURIComponent(id)}/collaborators`,
+      params,
+      options
+    );
+  }
+  /**
+   * Ends somebody's access, or withdraws an invitation they never accepted.
+   *
+   * Nothing was ever copied into their account - a collaborator SEES the
+   * owner's memories rather than holding a duplicate - so this is one write
+   * and not a cascade, and there is no orphaned copy left behind.
+   *
+   * A body on a DELETE, matching `removeMemories` above. The alternative is an
+   * address in a path segment, where every `.`, `+` and `@` is a chance for a
+   * proxy or a router to normalise somebody else's email into the one that
+   * gets revoked.
+   */
+  async unshare(id, email, options) {
+    return this.#http.delete(
+      `/api/v1/sharing/spaces/${encodeURIComponent(id)}/collaborators`,
+      { email },
+      options
+    );
+  }
+  /**
+   * Changes what an existing collaborator may do. Never invites anybody.
+   *
+   * The quiet one. Moving somebody from `viewer` to `owner` sends no
+   * invitation and needs no acceptance, and afterwards they can share the
+   * Space onward and revoke the person who promoted them. Show your user what
+   * `owner` means before you send this, not after.
+   */
+  async setRole(id, params, options) {
+    return this.#http.patch(
+      `/api/v1/sharing/spaces/${encodeURIComponent(id)}/collaborators`,
+      params,
+      options
+    );
+  }
 };
 
 // src/resources/ingestion.ts
@@ -950,6 +1075,121 @@ var Conversations = class {
   }
 };
 
+// src/resources/google.ts
+var Google = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  /** Files by name, newest first. Omit the query for recently changed ones. */
+  async searchDrive(params = {}, options) {
+    return this.#http.get(
+      "/api/v1/google/drive/files",
+      {
+        ...params.query !== void 0 ? { query: params.query } : {},
+        ...params.limit !== void 0 ? { limit: params.limit } : {}
+      },
+      options
+    );
+  }
+  async getDriveFile(fileId, options) {
+    return this.#http.get(
+      `/api/v1/google/drive/files/${encodeURIComponent(fileId)}`,
+      void 0,
+      options
+    );
+  }
+  /**
+   * The bytes of a Drive file.
+   *
+   * A Google Doc, Sheet or Slide holds no bytes of its own and is exported on
+   * the way - a document as PDF, a spreadsheet as CSV - so `filename` comes
+   * back describing what it BECAME. Writing it under the id instead produces a
+   * file nothing will open.
+   */
+  async downloadDriveFile(fileId, options) {
+    return this.#http.getBytes(
+      `/api/v1/google/drive/files/${encodeURIComponent(fileId)}/content`,
+      void 0,
+      options
+    );
+  }
+  /**
+   * Writes a file into the user's Drive.
+   *
+   * Needs one of the Drive write permissions on their connection. A read-only
+   * grant is refused by Google, and the error names the missing permission
+   * rather than reporting a failed upload - one is fixed with a checkbox and
+   * the other sends somebody looking for a bug.
+   */
+  async saveToDrive(params, options) {
+    return this.#http.postBytes(
+      "/api/v1/google/drive/files",
+      params.bytes,
+      params.contentType ?? "application/octet-stream",
+      {
+        name: params.name,
+        ...params.folderId !== void 0 ? { folderId: params.folderId } : {}
+      },
+      options
+    );
+  }
+  /**
+   * Recent messages - senders, subjects and a one-line preview, never bodies.
+   *
+   * `query` is Gmail's own syntax passed through as written: `from:priya`,
+   * `has:attachment`, `newer_than:7d`. It selects within the connected mailbox
+   * and cannot reach another one.
+   */
+  async searchMail(params = {}, options) {
+    return this.#http.get(
+      "/api/v1/google/mail",
+      {
+        ...params.query !== void 0 ? { query: params.query } : {},
+        ...params.limit !== void 0 ? { limit: params.limit } : {}
+      },
+      options
+    );
+  }
+  /** One message, with its body and the names of what is attached. */
+  async readMail(messageId, options) {
+    return this.#http.get(
+      `/api/v1/google/mail/${encodeURIComponent(messageId)}`,
+      void 0,
+      options
+    );
+  }
+  /**
+   * The bytes of one attachment.
+   *
+   * Separate from `readMail` so listing a mailbox never drags attachments
+   * across the network: a message with a 40 MB deck should not cost 40 MB to
+   * summarise.
+   */
+  async downloadAttachment(messageId, attachmentId, options) {
+    return this.#http.getBytes(
+      `/api/v1/google/mail/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}`,
+      void 0,
+      options
+    );
+  }
+  /** Sends as the connected account. Needs the send permission. */
+  async sendMail(params, options) {
+    return this.#http.post("/api/v1/google/mail/send", params, options);
+  }
+  /** People in the user's contacts. Omit the query to list them. */
+  async contacts(params = {}, options) {
+    return this.#http.get(
+      "/api/v1/google/contacts",
+      {
+        ...params.query !== void 0 ? { query: params.query } : {},
+        ...params.limit !== void 0 ? { limit: params.limit } : {}
+      },
+      options
+    );
+  }
+};
+
 // src/resources/integrations.ts
 var Integrations = class {
   #http;
@@ -1087,6 +1327,8 @@ var PersistMemory = class {
   conflicts;
   conversations;
   integrations;
+  /** Drive, mail and contacts on the user's connected Google account. */
+  google;
   health;
   agent;
   #http;
@@ -1103,6 +1345,7 @@ var PersistMemory = class {
     this.conflicts = new Conflicts(this.#http);
     this.conversations = new Conversations(this.#http);
     this.integrations = new Integrations(this.#http);
+    this.google = new Google(this.#http);
     this.health = new Health(this.#http);
     this.agent = new Agent(this.#http);
   }