openmates 0.29.0-alpha.9 → 0.31.0-alpha.1

package/CHANGELOG.md

@@ -1,7 +1,83 @@
 # Changelog — `openmates` npm package (CLI and SDK)
 
 Only SDK-relevant compatibility notes are recorded here. Release versions follow
-the product line (`0.29.x` alpha prereleases from `dev`, stable from `main`).
+the product line (`0.29.x` prereleases from `dev`, stable from `main`).
+
+## Unreleased
+
+### Breaking
+
+- Rust SDK: `Memories::create`, `update` and `types`, `MemoryInput`,
+  `hash_item_key` and `memory_plaintext` are removed, matching npm and Python
+  (removed 2026-11-07; the backend answers 410). `IdeaBucket::save_settings` now
+  returns the same refusal as npm/Python. `sdk.memories` is implemented in all
+  three SDKs.
+
+### Changed
+
+- `billing.downloadInvoice`, `billing.downloadCreditNote` and
+  `billing.usageExport` now declare the exported `RawDownload` type
+  (`contentType`, optional `filename`, `data: ArrayBuffer`); the runtime shape is
+  unchanged. `filename` is now always the last path component of the
+  `Content-Disposition` name, and is omitted for `.`/`..` names or a malformed
+  `filename*` encoding (previously such a header threw a `URIError`). Rust and
+  Python follow the same filename contract.
+
+Cross-language SDK alignment (npm, Python and Rust now behave the same; each case
+is a shared conformance vector):
+
+- **Malformed document slugs are refused locally.** `docs.show()` and
+  `docs.download()` throw the new `OpenMatesInvalidInputError`
+  (code `OPENMATES_SDK_INVALID_INPUT`) before any request for an empty slug,
+  `..`, a leading or trailing `/`, an empty or `.` segment, `\`, `:`, NUL or other
+  control characters, or a slug over 4096 bytes. Previously these reached the
+  server. Python raises the same error class, which is a `ValueError`.
+- **An empty Wikipedia `language` means English.** `wikipedia.search()`,
+  `summary()`, `learning()` and `article()` send `language=en` for `""`, the same
+  as an omitted language. Previously npm sent `language=` and the backend
+  rejected the request.
+- **Draft preview fallback counts Unicode characters.** When a draft has no saved
+  preview, `drafts.get()`/`list()` use the first 160 Unicode characters of the
+  markdown instead of 160 UTF-16 code units, so the preview never ends in half an
+  emoji. A saved but empty or undecryptable `encryptedDraftPreview` now gives
+  `preview: null` instead of falling back to the markdown.
+
+### Added (Python)
+
+- `OpenMatesClient(api_key=...)` mirrors the npm root client: a missing or blank
+  key raises `OpenMatesApiKeyRequiredError` (code `OPENMATES_SDK_API_KEY_REQUIRED`,
+  a subclass of `OpenMatesConfigError`) at construction, it never reads
+  `OPENMATES_API_KEY`, and it refuses the legacy `session`/`load_stored_session`
+  options. `OpenMates()` is unchanged.
+- Python `embeds.add_to_project()`/`remove_from_project()` resolve a Project
+  slug, name or id prefix before routing, as npm does.
+
+## 0.30.0
+
+### Breaking
+
+- **The SDK is API-key only and separate from the CLI login.** The root
+  `OpenMatesClient` export no longer loads the stored CLI login (the 0.29.x
+  `OPENMATES_SDK_CLI_SESSION` deprecation is complete). It is now the API-key
+  client: `new OpenMatesClient({ apiKey })`. Constructing it (or calling
+  `OpenMatesClient.load()`) without an `apiKey` throws
+  `OpenMatesApiKeyRequiredError` (code `OPENMATES_SDK_API_KEY_REQUIRED`), and the
+  `session` / `loadStoredSession` options are rejected. No SDK entrypoint reads
+  CLI state files or the keychain, so an SDK script can use a different account
+  from the logged-in CLI. `SDK_CLI_SESSION_DEPRECATION_CODE` is removed.
+
+  **Migration:** create an API key in Settings → Developers and pass it
+  explicitly (`new OpenMatesClient({ apiKey })` or `new OpenMates({ apiKey })`).
+  The key decrypts your chats locally with its own wrapped account key; nothing
+  else is needed. The `openmates` command line keeps its own login and is
+  unaffected.
+
+### Deprecated
+
+- `SessionClient.loginPassword()` / `importSession()` in `openmates/sdk/v1`. Public
+  SDKs are API-key only; these login modes are removed once every capability they
+  offer is available through API-key authentication (open work tracked in
+  `config/sdk-capabilities.json`).
 
 ## 0.29.x
 

package/README.md

@@ -62,7 +62,7 @@ openmates whoami --json
 The CLI displays a QR code or pair PIN. Approve it in the OpenMates web app.
 During login, the CLI never asks for your account password.
 
-Switch to a dev account using an isolated profile; upgrading to an alpha release
+Switch to a dev account using an isolated profile; upgrading to a prerelease
 preserves your existing login and does not change the API server:
 
 ```bash
@@ -157,6 +157,8 @@ openmates settings --help
 openmates settings account export data --json
 openmates settings memories list --json
 openmates learning-mode status --json
+openmates learning-mode enable --age-group 16_18 --passcode <passcode> --no-collaborative-build
+openmates learning-mode collaborative on --passcode <passcode>
 openmates docs search "API keys"
 ```
 
@@ -375,23 +377,37 @@ Use `chats.send()` for anonymous AI chat with automatic routing; `apps.ai.ask()`
 requires an account. With an API key, use `saveToAccount: true` when you want the
 chat saved to the OpenMates account.
 
-### Deprecated: implicit CLI login in the root `OpenMatesClient`
+### API keys only, never the CLI login
 
-`new OpenMatesClient()` / `OpenMatesClient.load()` from the root `openmates`
-export still load the stored CLI login when no `session` is passed, but this is
-deprecated: SDK credentials must be explicit. It emits one `DeprecationWarning`
-with code `OPENMATES_SDK_CLI_SESSION` per process. Pass `session` explicitly,
-set `loadStoredSession: false`, or use `SessionClient` from `openmates/sdk/v1`.
-A later minor release will require explicit credentials (see `CHANGELOG.md`).
-The `openmates` command line is unaffected.
+The SDK authenticates only with an API key you pass explicitly (or configure via
+`OPENMATES_API_KEY`). It is completely separate from the `openmates` command
+line: it never reads the CLI's `~/.openmates/session.json`, its state directory
+or the OS keychain, so a script can use a different account than the one logged
+in to the CLI. Create an API key in Settings → Developers. Each key carries its
+own wrapped copy of your account key, so the SDK decrypts your chats locally,
+in memory, with only that key.
+
+Since 0.31.0 the root `OpenMatesClient` is the API-key client and requires
+`apiKey`; constructing it without one throws `OpenMatesApiKeyRequiredError`
+(code `OPENMATES_SDK_API_KEY_REQUIRED`). The former `session` and
+`loadStoredSession` options are rejected.
+
+```typescript
+import { OpenMatesClient } from "openmates";
+
+const om = new OpenMatesClient({ apiKey: process.env.MY_OPENMATES_KEY! });
+```
 
 ### Native session SDK (preview)
 
 `openmates/sdk/v1` exports `SessionClient`, `RustApiKeyClient` and related
 types. Every operation runs in the shared OpenMates Rust core through a native
 Node-API module loaded from `native/<platform>-<arch>.node`; the SDK never
-launches the CLI and never reads CLI login state. Credentials are explicit:
-log in with `loginPassword()` or import a caller-owned session. If the native
+launches the CLI and never reads CLI login state. Its password/imported-session
+login modes (`loginPassword()`, `importSession()`) are deprecated: public SDKs
+are API-key only, and these modes are removed once every capability they offer
+is available through API-key authentication (tracked in
+`config/sdk-capabilities.json`). Use an API key for new integrations. If the native
 module for your platform is missing or incompatible, construction throws
 `SessionClientError` with code `native_binding_unavailable` (no TypeScript
 fallback). The SDK is moving to one portable WebAssembly build of the core
@@ -402,12 +418,12 @@ artifacts are not yet published; from a source checkout run
 
 ## Versioning
 
-OpenMates shows the short product line, for example `v0.29`, in the web app.
+OpenMates shows the short product line, for example `v0.31`, in the web app.
 The npm package uses exact artifact versions:
 
-- `0.29.0-alpha.N` is a prerelease from the `dev` branch published under the
+- `0.31.0-alpha.N` is a prerelease from the `dev` branch published under the
   `alpha` npm tag.
-- `0.29.0` is a stable release from `main` published under the `latest` npm tag.
+- `0.31.0` is a stable release from `main` published under the `latest` npm tag.
 
 Install stable releases with `npm install -g openmates`. Install prereleases with
 `npm install -g openmates@alpha`.

package/dist/{chunk-QRCAXXAL.js → chunk-2RBBM2P4.js}

@@ -18,6 +18,39 @@ function codingIdentifierRanges(text) {
   return ranges;
 }
 
+// ../secret-scanner/src/embedReferenceRanges.ts
+var EMBED_LINK_TARGET = /\(embed:[^\s)]+\)/g;
+var JSON_FENCE_OPEN = "```json\n";
+var JSON_BLOCK = /```json\n([\s\S]*?)\n```/g;
+var EMBED_ID_MEMBER = /"embed_id"\s*:\s*"(?:\\.|[^"\\])*"|"embed_ids"\s*:\s*\[(?:\s*"(?:\\.|[^"\\])*"\s*,?)*\s*\]/g;
+function isEmbedReferenceJson(body) {
+  let parsed;
+  try {
+    parsed = JSON.parse(body.trim());
+  } catch {
+    return false;
+  }
+  return typeof parsed === "object" && parsed !== null && ("embed_id" in parsed || "embed_ids" in parsed);
+}
+function embedReferenceRanges(text) {
+  if (!text.includes("embed")) return [];
+  const ranges = [];
+  for (const match of Array.from(text.matchAll(EMBED_LINK_TARGET))) {
+    ranges.push({ start: match.index, end: match.index + match[0].length });
+  }
+  for (const match of Array.from(text.matchAll(JSON_BLOCK))) {
+    if (!isEmbedReferenceJson(match[1])) continue;
+    const bodyStart = match.index + JSON_FENCE_OPEN.length;
+    for (const member of Array.from(match[1].matchAll(EMBED_ID_MEMBER))) {
+      ranges.push({ start: bodyStart + member.index, end: bodyStart + member.index + member[0].length });
+    }
+  }
+  return ranges.sort((a, b) => a.start - b.start);
+}
+function overlapsAnyRange(start, end, ranges) {
+  return ranges.some((range) => start < range.end && end > range.start);
+}
+
 // ../ui/src/components/enter_message/services/piiDetectionService.ts
 function luhnCheck(cardNumber) {
   const digits = cardNumber.replace(/\D/g, "");
@@ -519,6 +552,7 @@ function detectPII(text, excludedIdsOrOptions = /* @__PURE__ */ new Set()) {
     });
   }
   const hasUrlExclusions = urlExclusionZones.length > 0;
+  const embedZones = embedReferenceRanges(text);
   if (text.length >= MIN_PII_TEXT_LENGTH) {
     for (const pattern of PII_PATTERNS) {
       if (hasDisabledCategories) {
@@ -532,6 +566,7 @@ function detectPII(text, excludedIdsOrOptions = /* @__PURE__ */ new Set()) {
         const startIndex = regexMatch.index;
         const endIndex = startIndex + matchText.length;
         if (pattern.type === "PHONE" && identifierRanges.some((range) => startIndex < range.end && endIndex > range.start)) continue;
+        if (overlapsAnyRange(startIndex, endIndex, embedZones)) continue;
         if (hasUrlExclusions) {
           const insideUrl = urlExclusionZones.some(
             (zone) => startIndex >= zone.start && endIndex <= zone.end
@@ -584,7 +619,7 @@ function detectPII(text, excludedIdsOrOptions = /* @__PURE__ */ new Set()) {
         const overlaps = coveredRanges.some(
           (range) => startIndex >= range.start && startIndex < range.end || endIndex > range.start && endIndex <= range.end || startIndex <= range.start && endIndex >= range.end
         );
-        if (!overlaps) {
+        if (!overlaps && !overlapsAnyRange(startIndex, endIndex, embedZones)) {
           const matchText = text.substring(startIndex, endIndex);
           const matchId = `pii-PERSONAL_DATA-${entry.id}-${startIndex}`;
           if (!hasExclusions || !excludedIds.has(matchId)) {
@@ -732,7 +767,8 @@ var ProjectFilePrivacy = class {
       const literal = text.slice(range.start, range.end);
       if (!(this.options.preserveMappedTokens && this.values.has(literal)) && (this.values.has(literal) || GENERATED_TOKEN.test(literal) || legacyToken(literal))) ranges.push(range);
     }
-    const overlaps = (start, end) => [...tokens, ...ranges].some((r) => start < r.end && end > r.start);
+    const shields = [...tokens, ...embedReferenceRanges(text)];
+    const overlaps = (start, end) => [...shields, ...ranges].some((r) => start < r.end && end > r.start);
     for (const mapping of Array.from(this.values.values()).sort((a, b) => b.original.length - a.original.length)) {
       let start = text.indexOf(mapping.original);
       while (start !== -1) {
@@ -748,7 +784,7 @@ var ProjectFilePrivacy = class {
       for (const range of enhanced) {
         if (!Number.isInteger(range.start) || !Number.isInteger(range.end) || range.start < 0 || range.end <= range.start || range.end > text.length) fail("pii_invalid_semantic_range");
         let fragments = [{ ...range }];
-        for (const shield of [...tokens, ...ranges]) fragments = fragments.flatMap((part) => {
+        for (const shield of [...shields, ...ranges]) fragments = fragments.flatMap((part) => {
           if (part.start >= shield.end || part.end <= shield.start) return [part];
           return [
             part.start < shield.start ? { ...part, end: shield.start } : null,