@persistmemory/sdk 0.1.1 → 0.2.0

package/dist/resources/google.d.ts

@@ -0,0 +1,84 @@
+import type { HttpClient, RequestOptions } from "../http.js";
+import type { DriveFile, MailMessage, MailSummary, Person, SaveToDriveParams, SearchDriveParams, SearchMailParams } from "../types.js";
+/**
+ * A user's own Google, through this API rather than through Google.
+ *
+ * The distinction is the point. Google's tokens live encrypted on the server
+ * and never reach a client, so an API key that leaks is an API key - not a
+ * mailbox. Nothing here takes a Google credential, and nothing here ever will.
+ *
+ * Every method answers 409 when there is no connected account, or when Google
+ * has stopped renewing one. Neither is a server fault and neither is fixed by
+ * retrying: the user has to connect or reconnect at
+ * persistmemory.com/dashboard/connect, and the error message says so.
+ */
+export declare class Google {
+    #private;
+    constructor(http: HttpClient);
+    /** Files by name, newest first. Omit the query for recently changed ones. */
+    searchDrive(params?: SearchDriveParams, options?: RequestOptions): Promise<{
+        data: DriveFile[];
+    }>;
+    getDriveFile(fileId: string, options?: RequestOptions): Promise<DriveFile>;
+    /**
+     * 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.
+     */
+    downloadDriveFile(fileId: string, options?: RequestOptions): Promise<{
+        bytes: Uint8Array;
+        contentType: string;
+        filename?: string;
+    }>;
+    /**
+     * 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.
+     */
+    saveToDrive(params: SaveToDriveParams, options?: RequestOptions): Promise<DriveFile>;
+    /**
+     * 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.
+     */
+    searchMail(params?: SearchMailParams, options?: RequestOptions): Promise<{
+        data: MailSummary[];
+    }>;
+    /** One message, with its body and the names of what is attached. */
+    readMail(messageId: string, options?: RequestOptions): Promise<MailMessage>;
+    /**
+     * 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.
+     */
+    downloadAttachment(messageId: string, attachmentId: string, options?: RequestOptions): Promise<{
+        bytes: Uint8Array;
+        contentType: string;
+    }>;
+    /** Sends as the connected account. Needs the send permission. */
+    sendMail(params: {
+        to: string;
+        subject: string;
+        body: string;
+        replyToMessageId?: string;
+    }, options?: RequestOptions): Promise<{
+        id: string;
+    }>;
+    /** People in the user's contacts. Omit the query to list them. */
+    contacts(params?: {
+        query?: string;
+        limit?: number;
+    }, options?: RequestOptions): Promise<{
+        data: Person[];
+    }>;
+}

package/dist/types.d.ts

@@ -494,7 +494,98 @@ export interface UpdateIntegrationParams {
     readonly enabled?: boolean;
     readonly spaceIds?: readonly string[];
 }
+/** A file asked of one of the caller's own machines. */
+export interface AgentRequest {
+    readonly id: string;
+    readonly surface: string;
+    readonly kind: string;
+    /** The path that was asked for, on the machine that was asked. */
+    readonly path: string;
+    readonly status: string;
+    /**
+     * An opaque storage key, and deliberately not a URL.
+     *
+     * Nothing outside the server can do anything with it. Call `downloadLink`
+     * for something that opens.
+     */
+    readonly resultKey?: string;
+    readonly resultBytes?: string;
+    readonly resultType?: string;
+    readonly error?: string;
+    readonly createdAt: string;
+    readonly completedAt?: string;
+}
+export interface AgentDownloadLink {
+    /**
+     * A bearer credential for one file, in URL form. Short-lived.
+     *
+     * Do not log it, store it, or hand it anywhere the file itself would not be
+     * safe: whoever holds this URL holds the bytes until it expires.
+     */
+    readonly downloadUrl: string;
+    readonly method: "GET";
+    readonly filename: string;
+    readonly contentType: string;
+    readonly sizeBytes?: number;
+    readonly expiresInSeconds: number;
+}
 export interface HealthResponse {
     readonly status: string;
     readonly [key: string]: unknown;
 }
+export interface DriveFile {
+    readonly id: string;
+    readonly name: string;
+    readonly mimeType: string;
+    readonly size?: number;
+    readonly modifiedTime?: string;
+    readonly link?: string;
+    readonly owner?: string;
+    /** True for Docs, Sheets and Slides, which have no bytes of their own. */
+    readonly native: boolean;
+}
+export interface SearchDriveParams {
+    readonly query?: string;
+    readonly limit?: number;
+}
+export interface SaveToDriveParams {
+    readonly name: string;
+    readonly bytes: Uint8Array;
+    readonly contentType?: string;
+    readonly folderId?: string;
+}
+export interface MailSummary {
+    readonly id: string;
+    readonly threadId?: string;
+    readonly from?: string;
+    readonly to?: string;
+    readonly subject?: string;
+    readonly date?: string;
+    /** Gmail's own one-line preview. Never the whole body. */
+    readonly snippet?: string;
+    readonly unread: boolean;
+    readonly hasAttachments: boolean;
+}
+export interface MailAttachment {
+    readonly id: string;
+    readonly filename: string;
+    readonly mimeType: string;
+    readonly size?: number;
+}
+export interface MailMessage extends MailSummary {
+    readonly body: string;
+    /** Named, not fetched. Use `downloadAttachment` for the bytes. */
+    readonly attachments: readonly MailAttachment[];
+}
+export interface SearchMailParams {
+    /** Gmail search syntax: `from:priya`, `has:attachment`, `newer_than:7d`. */
+    readonly query?: string;
+    readonly limit?: number;
+}
+export interface Person {
+    readonly id: string;
+    readonly name?: string;
+    readonly emails: readonly string[];
+    readonly phones: readonly string[];
+    readonly organisation?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@persistmemory/sdk",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "The official TypeScript client for the PersistMemory API",
   "license": "MIT",
   "author": "PersistMemory",