用 AI 打造 Zindies 應用程式

這是給 AI 的指南，協助創作者與店家以 Zindies 公開 API（OAuth / REST）打造自己的應用程式（主要是 UI）。

原則上產出依賴極少、以單一 HTML + JavaScript 運作的成品，開啟檔案即可試用。

主要讀者是 AI 編碼代理。設想讓創作者與店家快速打造自己專用的小工具來使用。

給 AI / 爬蟲的 Markdown 版本在此 → /build-with-ai.md

連線資訊

請先取得 OpenAPI 規格，並以其為端點、參數、回應的唯一正本。請勿憑空臆造欄位名稱。

權杖有兩種，請依用途選擇。

PAT — 創作者/店家打造自用工具時最簡單。等同全 scope、無 Anchor 限制，從畫面發行。 (https://zindies.co/user/api)
OAuth 2.0 (Authorization Code + PKCE) — 適用於分發給多位使用者的應用程式。可用 scope 與 Anchor（目標實體）限縮存取範圍。 (https://developer.zindies.co/applications)
scopes: profile:read profile:write creations:read creations:write announcements:read announcements:write events:read events:write analytics:read

請勿將權杖直接寫入原始碼或提交到儲存庫。分發型應用請使用限縮 scope 與 Anchor 的 OAuth；即使是個人工具，也要從輸入欄或安全儲存讀取權杖。

api.zindies.co 已設定 CORS，瀏覽器即可直接呼叫。驗證一律使用 Authorization 標頭的 Bearer 權杖（不需 Cookie）。

範圍	允許的方法	Path
讀取公開資料	`GET`	`/v1/*`
個人領域（收藏·活動參加等）	`GET / POST / DELETE`	`/v1/me/*`
Anchor 之下的內容寫入（作品·公告·活動）	`GET / POST / PATCH / DELETE`	`/v1/creators/:token/, /v1/places/:token/`

語意：暖色 =「個別」實體（creator / creation / place）；冷色 =「聚集·發佈」（event / announcement）。詳細欄位請參閱 OpenAPI 規格。

實體	角色	主要欄位
創作者 `Creator`	創作者（製作者）。暖色識別色	`token name title bio photo_url url`
作品 `Creation`	作品（ZINE）。暖色識別色	`token title description released_year price photo_url creators url`
店家 `Place`	店家（販售店）。暖色識別色	`token name address latitude longitude place_type url`
活動 `Event`	活動（day / period）。冷色識別色	`event_type title started_at start_date place creators booths url`
Announcement `Announcement`	來自創作者/作品/店家的公告（polymorphic）	`title body audience announceable_type created_at`

GET / POST / PATCH / DELETE /v1/creators/:creator_token/creations (scope: creations:write)
GET / POST / PATCH / DELETE /v1/creators/:creator_token/announcements (scope: announcements:write)
GET / POST / PATCH / DELETE /v1/creators/:creator_token/events (scope: events:write)
GET / POST / PATCH / DELETE /v1/places/:place_token/announcements (scope: announcements:write)
GET / POST / PATCH / DELETE /v1/places/:place_token/events (scope: events:write)

內容寫入會巢狀在 creator / place 的權杖之下。使用 OAuth 時，所用權杖必須綁定到目標創作者/店家（Anchor）。目標權杖可從 /v1/me/entities 取得。

POST   /v1/creators/:creator_token/creations
PATCH  /v1/creators/:creator_token/creations/:id
DELETE /v1/creators/:creator_token/creations/:id

所有 GET 共用的查詢慣例。清單會回傳 ETag / Last-Modified，可用條件式 GET 進行快取。

回應一律為 JSON。錯誤採 { "error": "...", "message": "..." } 格式，401 = 驗證錯誤、404 = not_found、400 = 參數錯誤。