API Szkic
Najpierw uczciwy status: SyncPocket App nie ma jeszcze publicznego sieciowego API. Ta strona dokumentuje, z czym można integrować się już dziś, oraz przedstawia szkic propozycji API, które planujemy udostępnić — opublikowany wcześnie, żeby przyszli partnerzy i deweloperzy mogli zgłosić uwagi, zanim cokolwiek zostanie zamrożone.
Na czym można budować już dziś
SyncPocket App działa lokalnie, a jej obecną powierzchnią integracji jest udokumentowany format na dysku:
- Odczyt archiwum:
~/Library/Application Support/MemoryApp/items.jsonto wersjonowanyHistoryEnvelopezawierający elementy i definicje Tablic; payload binarny leży obok wblobs/. - Reużycie modelu:
MemoryKitzawiera dokładne modele elementów i Tablic, reguły retencji, zapis oraz interfejs synchronizacji — tylko Foundation/CryptoKit.
Zasada praktyczna: traktuj items.json jako tylko-do-odczytu z zewnątrz. Jeśli zapiszesz do niego, gdy aplikacja działa, Twoje zmiany mogą zostać nadpisane. Bezpieczne API zapisu to dokładnie to, czemu służy poniższa propozycja.
To nie jest API: synchronizacja iCloud
Podpisane buildy z uprawnieniami używają CloudKitSyncEngine i prywatnej bazy CloudKit użytkownika; izolowane testy UI używają NoopSyncEngine. To szczegół implementacyjny, nie publiczne API — nie ma serwerów danych SyncPocket App do wywołania, a osoby trzecie nie uzyskują w ten sposób dostępu do archiwum. Publiczne wydanie nadal wymaga podpisu produkcyjnego i testu na dwóch urządzeniach.
Obecne kierowanie do elementu z przypomnienia
Lokalne powiadomienie zapisuje stabilny UUID elementu w metadanych i kieruje prosto do jego szczegółów. Router iOS rozpoznaje też wewnętrzną postać memoryapp://item/<UUID>. Dziś jest to kontrakt nawigacji należący do aplikacji, a nie zarejestrowane publiczne API automatyzacji.
Szkic propozycji: lokalne API automatyzacji
Pierwsze publiczne API planujemy jako lokalne (aplikacja działa na maszynie użytkownika i jest właścicielem lokalnych danych), prawdopodobnie w formie URL scheme i/lub interfejsu wiersza poleceń. Zarys:
| Operacja | Zarys | Cel |
|---|---|---|
| Zapytanie o historię | memoryapp://search?q=…&type=link | Integracje z launcherami/automatyzacją (Raycast, Alfred, Skróty). |
| Otwarcie elementu | memoryapp://item/<UUID> | Ten sam stabilny cel co w lokalnym powiadomieniu. |
| Dodanie elementu | memoryapp://add?text=… | Pozwolić innym narzędziom bezpiecznie dokładać do pamięci. |
| Przypięcie / odpięcie | memoryapp://pin?id=… | Automatyzacja wokół często używanych snippetów. |
| Dodanie do Tablicy | memoryapp://board/add?item=…&board=… | Porządkowanie bez bezpośredniej edycji archiwum. |
| Ustawienie przypomnienia | memoryapp://remind?id=…&at=… | Zaplanowanie lokalnego powiadomienia otwierającego element. |
Szkic propozycji: zdalne API
Jeśli/gdy powstanie komponent hostowany (np. dla współdzielonych Tablic albo integracji partnerskich), API ma wyglądać tak. Wszystko poniżej jest propozycją i może się zmienić bez zapowiedzi.
Konwencje
- Bazowy URL:
https://api.syncpocket.app/v1(zarezerwowany, nieaktywny). - JSON na wejściu/wyjściu; UTF-8; znaczniki czasu ISO 8601.
- Autoryzacja:
Authorization: Bearer <token>(tokeny per użytkownik, z zakresami). - Wersjonowanie w ścieżce (
/v1); zmiany łamiące tylko ze zmianą wersji.
Zasób: Item
Format przesyłowy odzwierciedla dyskowy ClipItem, z datami w ISO 8601 i zawartością jako URL-e:
{
"id": "5b1e9c2a-8f1d-4a5e-9c77-2a1b3c4d5e6f",
"type": "color", // text | link | color | image | file
"date": "2026-07-07T17:24:00Z",
"createdAt": "2026-07-07T17:24:00Z",
"plainText": "#FF6B6B",
"sourceAppName": "Figma",
"pinned": false,
"boardIDs": ["f0000000-0000-4000-8000-000000000001"],
"reminderDate": "2026-07-15T14:00:00Z",
"contentHash": "sha256:a1b2c3…"
}Endpointy (zarys)
| Metoda i ścieżka | Opis |
|---|---|
GET /v1/items | Lista elementów. Filtry: type, pinned, board, q i since; paginacja kursorem. |
POST /v1/items | Dodanie elementu. Serwer liczy contentHash i deduplikuje — wysłanie istniejącej treści podbija ją na górę i zwraca istniejący element. |
GET /v1/items/{id} | Pobranie jednego elementu (z linkami do zawartości). |
PATCH /v1/items/{id} | Aktualizacja pól zmiennych, m.in. pinned, boardIDs i reminderDate. |
DELETE /v1/items/{id} | Usunięcie elementu. |
GET /v1/boards | Lista Pinned, Loved, Saved i własnych Tablic. |
POST /v1/boards | Utworzenie nazwanej własnej Tablicy. |
PATCH /v1/boards/{id} | Zmiana nazwy własnej Tablicy. |
DELETE /v1/boards/{id} | Usunięcie własnej Tablicy bez usuwania jej elementów. |
Kontrakt deduplikacji
Ta sama semantyka hashu treści co w formacie lokalnym: tożsamością jest sha256 treści. Klienci mogą policzyć hash sami, żeby sprawdzić istnienie przed wysłaniem zawartości.
Uwagi i kontakt
Budujesz wtyczkę do launchera, automatyzację, albo interesuje Cię partnerstwo? Powiedz nam, czego potrzebujesz od tego API, zanim powstanie — wczesny feedback to cały powód, dla którego ten szkic jest publiczny. Napisz: hello@syncpocket.app lub przez stronę Kontakt.