Przewodnik po API zespołów, udostępniania i połączeń

Wszystko na platformie DUST należy do zespołów i to zespoły uzyskują do niego dostęp. Ten przewodnik omawia cztery warstwy, które decydują o tym, kto co widzi:

1. Kontekst — w imieniu której organizacji i którego zespołu działa żądanie.
2. Udostępnianie — przyznawanie innemu zespołowi dostępu do rekordów i folderów jako przeglądający lub edytujący.
3. Połączenia — stałe porozumienie między dwoma zespołami (zwykle z różnych organizacji), które umożliwia udostępnianie i przesyłki.
4. Przesyłki i wydzielenia — przenoszenie lub tworzenie pochodnych rekordów ponad tymi granicami.

Pełne schematy: dokumentacja API.

Kontekst żądania

Tożsamość jest przechowywana w AuthD; API platformy określa zakres każdego wywołania za pomocą nagłówków:

Authorization: Bearer <authd-token>
Dust-Ctx-Org-Id: <organization-uuid>
Dust-Ctx-Team-Id: <team-uuid>

Nagłówek Dust-Ctx-Org-Id jest wymagany w wywołaniach w zakresie organizacji. Dust-Ctx-Team-Id wybiera zespół, w imieniu którego wykonywane jest działanie, i domyślnie wskazuje zespół główny organizacji (Dust-Ctx-Grp-Id to akceptowana starsza pisownia). Zobacz Uwierzytelnianie i Konwencje.

• GET /api/v1/me — bieżący użytkownik, sesja, aktywna organizacja i dostępne organizacje
• GET /api/v1/me/feature-flags — przełączniki funkcji dla wywołującego

Zespoły

Zespoły dzielą organizację na części, a rekordy, foldery i udostępnienia należą do zespołu. Aktualizacja metadanych zespołu zachowuje jego organizację i ID zespołu; niezadeklarowane właściwości aktualizacji są odrzucane.

Operacja	Metoda i ścieżka
Wyświetlenie listy zespołów, które widzisz	GET /api/v1/teams
Wyświetlenie listy połączonych zespołów partnerów	GET /api/v1/teams/connected
Tworzenie zespołów (administrator organizacji)	POST /api/v1/org/teams
Wyświetlenie listy wszystkich zespołów w organizacji (administrator organizacji)	GET /api/v1/org/teams
Aktualizacja / usunięcie zespołu (administrator organizacji)	PATCH / DELETE /api/v1/org/teams/{team_id}
Dodanie lub aktualizacja członkostw (administrator organizacji)	POST /api/v1/org/teams/members
Wyświetlenie listy / usunięcie członkostw (administrator organizacji)	GET / DELETE /api/v1/org/teams/members

GET /api/v1/teams obsługuje parametry q, role, rootId i includeLinked (aby uwzględnić połączone zespoły partnerów w selektorach). GET /api/v1/teams/connected zwraca listę zespołów partnerów osiągalnych przez aktywne połączenia — prawidłowych odbiorców udostępnień i przesyłek.

Udostępnianie

Udostępnienie przyznaje jednemu zespołowi dostęp do jednego obiektu — rekordu lub pakietu (folderu/kategorii) — w roli viewer lub editor. Uprawnienia są przechowywane jako krotki relacji, a dostęp może też wynikać pośrednio (udostępniony folder przekazuje dostęp do swojej zawartości), dlatego istnieją dwa modele odczytu: surowa lista uprawnień oraz podsumowanie efektywnego dostępu.

curl

curl -fsS "$APID_URL/api/v1/sharing" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Dust-Ctx-Team-Id: $DUST_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "item": "thread", "id": "'"$THREAD_ID"'", "teamId": "'"$PARTNER_TEAM_ID"'", "relation": "viewer" }
    ]
  }'

TypeScript

await client.sharing.add({
  items: [
    { item: "thread", id: threadId, teamId: partnerTeamId, relation: "viewer" },
  ],
});

Operacja	Metoda i ścieżka
Tworzenie udostępnień	POST /api/v1/sharing
Wyświetlenie listy udostępnień	GET /api/v1/sharing?direction=in|out
Aktualizacja relacji udostępnienia	PATCH /api/v1/sharing/{tuple_id}
Usunięcie udostępnień	DELETE /api/v1/sharing (treść: { "ids": […] })
Efektywny dostęp do jednego obiektu	GET /api/v1/sharing/access-summary?objectId=…&objectType=thread|bundle
Wszystko, co udostępniono jednemu partnerowi	GET /api/v1/sharing/partner-inventory?teamId=…

direction=out zwraca listę tego, co twój zespół udostępnił; direction=in — tego, co udostępniono jemu. Podsumowanie dostępu łączy bezpośrednie uprawnienia, dziedziczenie z folderów i relacje zespołów w efektywne uprawnienia do obiektu; inwentarz partnera to widok w ujęciu poszczególnych połączeń — przydatny przed wstrzymaniem lub zmianą połączenia.

Ułatwienia po stronie rekordów: GET /api/v1/threads/{thread_id}/shared (komu udostępniono ten rekord) i POST /api/v1/threads/permissions (co może zrobić wywołujący) — zobacz przewodnik po rekordach.

Połączenia

Połączenie (nazwa w API: team link) łączy dwa zespoły i warunkuje wszelką aktywność między zespołami. Ma dozwolony kierunek przepływu danych — send, receive lub send_receive, wyrażony z perspektywy zespołu wnioskującego — i jest nawiązywane w trzyetapowym uzgadnianiu: wnioskodawca tworzy połączenie, partner je akceptuje, a wnioskodawca potwierdza. Połączenia są identyfikowane przez code zaproszenia.

Operacja	Metoda i ścieżka
Utworzenie (zaproszenie)	POST /api/v1/connections — treść { "allow": "send" | "receive" | "send_receive", "email"? }
Wyświetlenie listy połączeń	GET /api/v1/connections
Pobranie / usunięcie jednego	GET / DELETE /api/v1/connections/{code}
Akceptacja (partner)	PATCH /api/v1/connections/accept
Odrzucenie (partner)	PATCH /api/v1/connections/reject
Potwierdzenie (wnioskodawca)	PATCH /api/v1/connections/confirm
Anulowanie	PATCH /api/v1/connections/cancel
Wstrzymanie / wznowienie	PATCH /api/v1/connections/pause / resume

Wstrzymanie połączenia zawiesza zależne od niego udostępnianie i przesyłki bez usuwania samego połączenia.

Zmiany kierunku

Zmiana kierunku aktywnego połączenia sama jest uzgadnianiem, dzięki czemu żadna ze stron nie może jednostronnie rozszerzyć przepływu danych — jeden z zespołów proponuje zmianę, drugi zespół ją akceptuje, a proponujący potwierdza; do czasu potwierdzenia obowiązuje dotychczasowy kierunek:

• POST /api/v1/connections/amend/propose — treść { "code", "allow" }
• PATCH /api/v1/connections/amend/accept / confirm / cancel

Udostępnienia, których przepływu nowy kierunek już nie dopuszcza, stają się nieaktywne zamiast zostać usunięte.

Przesyłki

Przesyłka (przestrzeń nazw API: /api/v1/transfers, starsze nazewnictwo) przekazuje własność rekordów połączonemu zespołowi: przygotuj szkic manifestu, wyślij go, a odbiorca udzieli odpowiedzi. Punkty końcowe w kolejności cyklu życia:

Etap	Metoda i ścieżka
Utworzenie szkicu	POST /api/v1/transfers
Dodanie / aktualizacja / usunięcie pozycji manifestu	POST /api/v1/transfers/{transfer_id}/items, PATCH / DELETE …/items/{item_id}
Ustawienie rekordu podstawowego	PUT /api/v1/transfers/{transfer_id}/primary-thread
Wysłanie	POST /api/v1/transfers/{transfer_id}/send
Podgląd (odbiorca, po wysłaniu)	GET /api/v1/transfers/{transfer_id}/preview
Odpowiedź: przyjęcie / odrzucenie / prośba o zmiany	POST /api/v1/transfers/{transfer_id}/respond
Korespondencja	POST /api/v1/transfers/{transfer_id}/messages
Anulowanie (szkic, wysłana lub z prośbą o zmiany)	POST /api/v1/transfers/{transfer_id}/cancel
Ponowienie nieudanej przesyłki	POST /api/v1/transfers/{transfer_id}/retry
Porzucenie nieudanej przesyłki	POST /api/v1/transfers/{transfer_id}/abandon
Ponowne rozpoczęcie od manifestu zatrzymanej przesyłki	POST /api/v1/transfers/{transfer_id}/start-from-prior-manifest
Lista (widoki skrzynek)	GET /api/v1/transfers?box=inbox|outbox|sent
Pobranie jednej wraz z manifestem	GET /api/v1/transfers/{transfer_id}

Odpowiedź przyjmuje { "value": "accept" | "reject" | "request_changes" } (w przypadku prośby o zmiany wymagany jest reason). Lista obsługuje filtry box, view, status i direction=inbound|outbound.

Notatka

Ta tabela jest celowo jedynie mapą. Zawartość manifestu, działanie ujawnienia i znaczenie poszczególnych stanów opisano w sekcji Przesyłki; model pochodzenia, na którym opiera się widoczność danych między zespołami, opisano w sekcji Fabric.

Wydzielenia

Wydzielenie tworzy nowy rekord na podstawie istniejącego w obrębie twojego zespołu — z wybranym podzbiorem pól, plików i identyfikatorów — zwykle po to, aby przygotować dokładnie to, co zamierzasz udostępnić lub wysłać, a resztę zachować jako prywatną:

• POST /api/v1/slices — wydzielenie jednego rekordu (folder docelowy wybierany przez bundleId, pola przez fields, …)
• POST /api/v1/slices/batch — utworzenie wielu rekordów w jednej operacji
• GET /api/v1/slices/{slice_id} — wydzielenie wraz z jego linkami Fabric

Powiązane strony

• Model podstawowy — jak zespoły, udostępnienia i połączenia wpisują się w model domeny
• Przesyłki — semantyka cyklu życia przesyłki
• Fabric — pochodzenie i ujawnianie między organizacjami
• Dokumentacja API — pełne schematy wszystkich powyższych punktów końcowych