@persistmemory/sdk 0.2.0 → 0.4.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, WorkingSpace } from "../types.js";
 /**
  * Spaces: a boundary around a set of memories.
  *
@@ -36,12 +36,22 @@ export declare class Spaces {
      * `delete` never destroys a memory that is filed in another Space as well —
      * that one is detached and left alone. `deleted` and `kept` come back so you
      * can say what actually happened.
+     *
+     * `moveTo` NAMES WHERE THE STRANDED ONES GO, and is refused-into rather than
+     * required: most deletions strand nothing, because everything in the Space
+     * is also filed elsewhere, and demanding a destination for those would be a
+     * question about nothing. When something WOULD be left in no Space at all,
+     * the server answers 400 naming this field. It used to file them into the
+     * account's default, which no longer exists — nothing picks a Space on
+     * anybody's behalf, so "keep these" has no answer unless you say where.
      */
     delete(id: string, params: {
         readonly memories: "keep" | "delete";
+        readonly moveTo?: string;
     }, options?: RequestOptions): Promise<{
         deleted: number;
         kept: number;
+        rehomed?: number;
     }>;
     /**
      * Merges Spaces into a NEW one, leaving every source exactly as it was.
@@ -60,29 +70,46 @@ export declare class Spaces {
         added: number;
     }>;
     /**
-     * The Space this account files into when a capture names none.
+     * Which Space a context is working in.
+     *
+     * `chosen` absent means NOTHING sent from that context is kept — there is no
+     * default behind it and nothing picks one. The reply used to carry a
+     * `fallback` for that case and no longer can.
      *
-     * `{}` — an object with no `space` — means there is no default, which is the
-     * normal state rather than a gap. It is also what comes back after the Space
-     * somebody chose has been deleted.
+     * `profile` is the command line's own profile name, and `surface` says which
+     * context is being asked about: `cli` for this profile, `email` for the
+     * account's ingest address. Between them they are the whole of what a caller
+     * may say about where it is working — the server builds the scope key
+     * itself, so this can never read or move where a chat is filing.
      */
-    getDefault(options?: RequestOptions): Promise<{
-        space?: Space;
-    }>;
-    /** `null` clears it. Not the same as omitting it, which is why the type says so. */
-    setDefault(spaceId: string | null, options?: RequestOptions): Promise<{
-        space?: Space;
-    }>;
+    working(params?: {
+        readonly profile?: string;
+        readonly surface?: "cli" | "email";
+    }, options?: RequestOptions): Promise<WorkingSpace>;
+    /**
+     * Works in one from here on. `null` stops working in any.
+     *
+     * Takes an id or a NAME, because that is how a person says it. `null` rather
+     * than an omitted field: "clear this" and "I did not mention it" are
+     * different instructions, and clearing means this context keeps nothing
+     * until a Space is chosen again.
+     */
+    chooseWorking(space: string | null, params?: {
+        readonly profile?: string;
+        readonly surface?: "cli" | "email";
+    }, options?: RequestOptions): Promise<WorkingSpace>;
     /** Renaming, retention, and archiving - `archived` is a field, not a verb. */
     update(id: string, params: UpdateSpaceParams, options?: RequestOptions): Promise<Space>;
     /**
      * 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 +127,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>>;
@@ -116,6 +141,21 @@ export interface ListMemoriesParams {
 export interface RememberParams {
     readonly text: string;
     readonly title?: string;
+    /**
+     * The Spaces this is filed into. REQUIRED BY THE SERVER, though optional
+     * here.
+     *
+     * A capture with no Space is refused with a 400 that names this account's
+     * Spaces. It used to be filed into the account's default, its oldest Space,
+     * or a new one made for it — three destinations nobody chose — and none of
+     * those exists now: a Space is chosen or nothing is kept.
+     *
+     * It stays optional in the TYPE so that a caller upgrading this package gets
+     * the explanation from the server, in a sentence listing the Spaces they
+     * actually have, rather than a compile error that says "required" and leaves
+     * them looking for a list. Every call that omits it now fails at runtime;
+     * that break is intended and is the whole change.
+     */
     readonly spaceIds?: readonly string[];
 }
 /**
@@ -222,6 +262,35 @@ export interface Space {
     /** Set when archived. An archived Space is hidden, not deleted. */
     readonly archivedAt?: string;
 }
+/**
+ * Where one context is filing, and whether anybody decided it.
+ *
+ * TWO FIELDS BECAUSE THEY ARE TWO FACTS, and merging them is the mistake this
+ * shape exists to make impossible. `chosen` is a Space somebody picked here: it
+ * narrows what a question is answered from as well as where a note lands.
+ * `fallback` is the account's own default, adopted automatically for captures
+ * that name none, and it narrows NOTHING — reading through it would silently
+ * scope every question the person ever asked to a Space they never picked.
+ *
+ * Neither present means no Space can be named at all, which is a real state
+ * rather than a gap: an account with no Spaces yet.
+ */
+export interface WorkingSpace {
+    /** The context this answers about — `cli:default`, `email`. The server owns it. */
+    readonly scope: string;
+    /**
+     * The Space chosen for this context.
+     *
+     * ABSENT MEANS NOTHING IS KEPT from it, not "kept somewhere else". There
+     * used to be a `fallback` beside this — the account-wide Space a capture
+     * fell into when nobody chose — and it is gone with the setting itself: a
+     * Space is chosen or the capture is refused.
+     */
+    readonly chosen?: {
+        readonly id: string;
+        readonly name: string;
+    };
+}
 export interface CreateSpaceParams {
     readonly name: string;
     readonly description?: string;
@@ -241,6 +310,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;

package/package.json

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