@persistmemory/sdk 0.1.2 → 0.3.0

package/dist/resources/spaces.d.ts

@@ -1,6 +1,6 @@
 import type { HttpClient, RequestOptions } from "../http.js";
 import { Paginated } from "../pagination.js";
-import type { CreateSpaceParams, ListSpacesParams, Memory, Space, UpdateSpaceParams } from "../types.js";
+import type { CreateSpaceParams, ListSpacesParams, Memory, ShareSpaceParams, Space, SpaceCollaborator, GrantableSpaceRole, UpdateSpaceParams } from "../types.js";
 /**
  * Spaces: a boundary around a set of memories.
  *
@@ -78,11 +78,13 @@ export declare class Spaces {
     /**
      * 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: string, params?: {
         readonly limit?: number;
@@ -100,4 +102,69 @@ export declare class Spaces {
     removeMemories(id: string, memoryIds: readonly string[], options?: RequestOptions): Promise<{
         removed: number;
     }>;
+    /**
+     * 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: string, params?: {
+        readonly limit?: number;
+    }, options?: RequestOptions): Paginated<SpaceCollaborator>;
+    /**
+     * 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.
+     */
+    share(id: string, params: ShareSpaceParams, options?: RequestOptions): Promise<SpaceCollaborator>;
+    /**
+     * 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.
+     */
+    unshare(id: string, email: string, options?: RequestOptions): Promise<{
+        email: string;
+    }>;
+    /**
+     * 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.
+     */
+    setRole(id: string, params: {
+        readonly email: string;
+        readonly role: GrantableSpaceRole;
+    }, options?: RequestOptions): Promise<SpaceCollaborator>;
 }

package/dist/types.d.ts

@@ -70,10 +70,35 @@ export interface Temporal {
     /** True while the claim is believed to hold. */
     readonly current: boolean;
 }
+/**
+ * Whoever owns a memory that is not yours.
+ *
+ * A name, never a user id: the API does not send one, and nothing here takes
+ * one. `name` is absent when the account set neither a display name nor a
+ * username, which is why `mine` below and not this is what says the memory
+ * belongs to somebody else.
+ */
+export interface SharedBy {
+    readonly name: string;
+}
 export interface Memory {
     readonly id: string;
     readonly type: MemoryType;
     readonly state: MemoryState;
+    /**
+     * Whether YOU own this memory.
+     *
+     * Not always true. A listing returns everything your key may see, and that
+     * includes memories owned by people who shared a Space with you — filed in
+     * the same Spaces you file into, so `spaceIds` will not tell them apart.
+     * Anything that reads a memory back to a person, or puts one in a model's
+     * context, has to carry this: an unmarked claim from a colleague is
+     * indistinguishable from one of your own, and a model will state it in your
+     * voice.
+     */
+    readonly mine: boolean;
+    /** Who it belongs to, when `mine` is false and the API can name them. */
+    readonly sharedBy?: SharedBy;
     readonly title: string;
     readonly content: string;
     readonly value?: Readonly<Record<string, unknown>>;
@@ -241,6 +266,56 @@ export interface ListSpacesParams {
     readonly cursor?: string;
     readonly includeArchived?: boolean;
 }
+/**
+ * What somebody you shared a Space with may do with it.
+ *
+ * A WIDENING SCALE: every role sees everything filed in the Space, and the
+ * role decides only what they may do BESIDES read. `viewer` reads it,
+ * `editor` also files new memories into it, `owner` can additionally share it
+ * onward and revoke people - including you.
+ */
+export type SpaceRole = "viewer" | "editor" | "owner";
+/**
+ * A role that may actually be GRANTED, which is not every role.
+ *
+ * `owner` is real — the Space's owner holds it and a collaborator listing
+ * shows it — but no request can hand it out. `POST /collaborators` and
+ * `PATCH /collaborators/:id` both take `["viewer", "editor"]`, and the store
+ * throws `CannotGrantOwnership` behind them, so a call carrying `owner` is
+ * refused with a 400 every time.
+ *
+ * Separate from `SpaceRole` rather than narrowing it, because the two are
+ * genuinely different questions: what a collaborator MAY BE is three values,
+ * what you may SET them to is two. Typing the parameters as `SpaceRole` made
+ * the compiler accept a call the server always rejects — a typed client whose
+ * types are wrong about the server is worse than an untyped one, because the
+ * error arrives at runtime after the type system said it was fine.
+ */
+export type GrantableSpaceRole = Exclude<SpaceRole, "owner">;
+/**
+ * One person who has been given, or merely offered, sight of a Space.
+ *
+ * `acceptedAt` is the field to read before you render anything. An invitation
+ * grants NOTHING until the recipient accepts, so a UI that shows an invited
+ * person the same way it shows an accepted one tells its user that somebody is
+ * reading their memories when nobody is - and read the other way, hides that
+ * an invitation never landed.
+ */
+export interface SpaceCollaborator {
+    readonly email: string;
+    readonly name?: string;
+    readonly role: SpaceRole;
+    readonly invitedBy?: string;
+    readonly invitedAt?: string;
+    /** Absent means they have accepted nothing and can see nothing. */
+    readonly acceptedAt?: string;
+}
+export interface ShareSpaceParams {
+    /** The person to offer the Space to, by address. */
+    readonly email: string;
+    /** See `GrantableSpaceRole` — `owner` cannot be given away. */
+    readonly role: GrantableSpaceRole;
+}
 export interface Source {
     readonly id: string;
     readonly provider: string;
@@ -533,3 +608,59 @@ 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.2",
+  "version": "0.3.0",
   "description": "The official TypeScript client for the PersistMemory API",
   "license": "MIT",
   "author": "PersistMemory",