mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-11 03:37:56 +00:00
672defc08b
Rewrites 339 TypeScript calls across 50 pages from the rc.5 `method({ namespace, body })` form to the shipped `method(namespace, { ... })` form, and aligns field names with the live v5 spec: `attach` to `include`, `authUrl` to `authorization`, `lastSync` to `latestRun`, `deletedCount` to `count`, and the paginated `namespaces.list()`.
Renames container tags to namespaces across concepts, connectors, integrations and snippets. The namespace pages keep container tag in the description, search keywords and a rename note so old searches still land, and the v3 reference page points at v5.
The migration guide's SDK table now covers both 5.0.0 SDKs, and the SDK integration page uses the real client options (`baseUrl`, `timeoutInSeconds`, `maxRetries`) and error classes.
60 lines
2.8 KiB
Text
60 lines
2.8 KiB
Text
Treat migration as a behavioral comparison, not a raw response snapshot update.
|
|
|
|
### Build deterministic fixtures
|
|
|
|
Use an isolated namespace with stable IDs and fixed source content. Include plaintext, URL, file, batch, metadata, grouping, profile facts, related memories, forgotten memories, and empty-result cases.
|
|
|
|
Record each legacy request, v5 request, expected semantic result, and intentional difference. Never compare generated IDs, signed URLs, timing, or JSON object order unless the contract guarantees them.
|
|
|
|
### Compare writes
|
|
|
|
- Repeated POST appends or diffs; PATCH replaces canonical content.
|
|
- Batch outcomes list accepted documents first, then failures, and surface partial failures; match by ID, not position.
|
|
- Metadata-only updates leave source content unchanged.
|
|
- Accepted writes are polled until processing reaches a terminal state.
|
|
|
|
### Compare reads and recall
|
|
|
|
- Document includes are absent when omitted and empty arrays when requested without results.
|
|
- Unified list responses populate only the selected resource array.
|
|
- `metadata` is always an object, `{}` when empty; it is never `null`.
|
|
- Search parity uses explicit v4-equivalent mode and threshold before testing v5 defaults.
|
|
- Profiles always contain static, dynamic, and bucket sections.
|
|
|
|
### Exercise boundaries
|
|
|
|
| Boundary | Cases |
|
|
| --- | --- |
|
|
| Namespace | Correct, missing, unauthorized, cross-namespace ID |
|
|
| Pagination | First, middle, final, empty, maximum limit |
|
|
| Filters | Every operator, nested AND/OR, invalid type, excessive depth |
|
|
| Deletion | All success, partial success, unknown IDs, semantic dry run |
|
|
| Settings | Admin, non-admin, null removal, invalid empty value |
|
|
|
|
### Classify differences
|
|
|
|
```text
|
|
same request intent
|
|
|
|
|
+-- same semantic result ------> parity
|
|
+-- documented v5 difference --> update assertion
|
|
+-- undocumented difference ----> block cutover
|
|
```
|
|
|
|
Do not normalize away an undocumented difference. Capture the request pair, namespace, IDs, response status, and minimal response fragments needed to reproduce it.
|
|
|
|
### Cut over by domain
|
|
|
|
1. Ship v5 request construction behind a per-domain flag.
|
|
2. Dual-read or shadow-call where side effects allow it.
|
|
3. Switch ingestion, content management, search, profiles, then settings independently.
|
|
4. Monitor validation failures, authorization failures, latency, empty-result rate, and processing failures.
|
|
5. Retain the legacy path until the observation window passes.
|
|
|
|
### Completion checklist
|
|
|
|
- No application API call accidentally uses a `/v5` prefix.
|
|
- Connector calls use `/ns/{namespace}/connectors` or `supermemory.connectors.*`, not `/v3/connections`.
|
|
- No legacy field aliases or response readers remain.
|
|
- Every changed default is either accepted intentionally or passed explicitly.
|
|
- Rollback restores the previous caller without requiring data repair.
|