@persistmemory/sdk 0.2.0 → 0.4.0

package/README.md

@@ -219,19 +219,28 @@ const { space, added } = await client.spaces.merge({
 Additive, never destructive. Both sources keep exactly what they had, a memory
 in both is filed once, and undoing it is deleting the Space that comes back.
 
-### The default Space
+### There is no default Space
 
-Where a capture lands when it names none — the Telegram bot with no `/space`
-set, an MCP `remember` with no `spaceIds`, a conversation started from a chat.
+A capture that names none is REFUSED. `client.memories.remember({ text })` with
+no `spaceIds` answers 400, naming the Spaces this account has; the Telegram bot
+with no `/space` set keeps nothing and says so; an MCP `remember` with no
+`spaceIds` and no `work_in_space` returns an error rather than filing. Nothing
+picks a Space on anybody's behalf.
+
+`spaces.setDefault` and `spaces.getDefault` are gone with the two endpoints
+they called. What replaces them is per-context rather than per-account: which
+Space THIS command line, or this account's ingest address, is working in.
 
 ```ts
-await client.spaces.setDefault(work.id);
-const { space } = await client.spaces.getDefault();  // {} when there is none
-await client.spaces.setDefault(null);                // back to nothing
+await client.spaces.chooseWorking(work.id);                   // this profile
+await client.spaces.chooseWorking(work.id, { surface: "email" }); // the inbox
+const here = await client.spaces.working();                   // { scope, chosen? }
+await client.spaces.chooseWorking(null);                       // stop; nothing is kept
 ```
 
-`null` clears it and is not the same as omitting the field. Having no default is
-the normal state, not a gap — nothing picks a Space on your behalf.
+`null` clears it and is not the same as omitting the field. `chosen` absent
+means nothing sent from that context is kept — not that it is kept somewhere
+else.
 
 ### Nesting, listing, updating, archiving
 

package/dist/index.cjs

@@ -654,6 +654,14 @@ var Spaces = class {
    * `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.
    */
   async delete(id, params, options) {
     return this.#http.delete(
@@ -677,21 +685,55 @@ var Spaces = class {
       options
     );
   }
+  /* ------------------------- where this is working ------------------------- */
+  /*
+      `getDefault` AND `setDefault` ARE GONE, with the endpoints they called.
+  
+      They read and wrote the account-wide Space a capture fell into when nobody
+      named one. Nothing falls anywhere now: a Space is chosen for the context
+      doing the capturing, or `remember` answers 400. Keeping the methods would
+      mean keeping two calls that 404, which is a worse break than removing them
+      because it looks like a server fault rather than a change.
+    */
   /**
-   * 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.
    */
-  async getDefault(options) {
-    return this.#http.get("/api/v1/spaces/default", void 0, options);
+  async working(params = {}, options) {
+    return this.#http.get(
+      "/api/v1/spaces/working",
+      {
+        ...params.profile !== void 0 ? { profile: params.profile } : {},
+        ...params.surface !== void 0 ? { surface: params.surface } : {}
+      },
+      options
+    );
   }
-  /** `null` clears it. Not the same as omitting it, which is why the type says so. */
-  async setDefault(spaceId, options) {
+  /**
+   * 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.
+   */
+  async chooseWorking(space, params = {}, options) {
     return this.#http.patch(
-      "/api/v1/spaces/default",
-      { spaceId },
+      "/api/v1/spaces/working",
+      {
+        space,
+        ...params.profile !== void 0 ? { profile: params.profile } : {},
+        ...params.surface !== void 0 ? { surface: params.surface } : {}
+      },
       options
     );
   }
@@ -702,17 +744,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
       )
     );
@@ -738,6 +785,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