@codecks/fetch 1.0.1 → 2.0.0

package/schema/models/account.md

@@ -1,104 +1,71 @@
 # account
 
+An organization and its settings.
+
 Key: `id`
 
 ## Fields
 
-- `id`: string
-- `subdomain`: string
-- `name`: string
-- `billingName`: string, optional
-- `billingLine1`: string, optional
-- `billingLine2`: string, optional
-- `billingZip`: string, optional
-- `billingCity`: string, optional
-- `billingCountryCode`: string, optional
-- `billingEmail`: string, optional
-- `netGiftAmount`: number
-- `persona`: string, optional
-- `createdAt`: Date (ISO string)
-- `disabledAt`: Date (ISO string), optional
-- `totalMediaByteUsage`: bigint
-- `isDisabled`: string
-- `milestonesEnabled`: string
-- `sprintsEnabled`: string
-- `priorityLabels`: object
-- `effortScale`: object
-- `statusChangeDurations`: object
-- `activeFeatureFlags`: object
-- `timeTrackingMode`: string
-- `maxTimeTrackingSegmentMsDuration`: number
-- `timeTrackingSwimLaneInfo`: boolean
-- `workdays`: string
-- `workflowMode`: string
-- `isLearning`: boolean
-- `isNonProfit`: boolean
-- `dependenciesEnabled`: boolean
-- `maxHandSlotCount`: number
-- `seats`: number
-- `activeProjectCount`: number
-- `billingType`: string
-- `allowInheritHeroCover`: boolean
-- `attachmentCoverMode`: string
-- `staffPermission`: string
-- `offeringTrial`: boolean
-- `coupon`: object, optional
-- `hideCompletedCardCountForDecks`: boolean
-- `visionBoardEnabled`: boolean
-- `fallbackEffort`: number
-- `timelineScaleType`: string
-- `startWeekday`: string
-- `disabledById`: string (foreign key ID) → user, optional
+- `allowInheritHeroCover`: `boolean` — **preview**
+  `true` makes the web app show a hero card's cover image on its sub cards, in place of their own.
+- `attachmentCoverMode`: `"none" | "first" | "last" | (string & {})` — **preview**
+  Which uploaded image attachment becomes the card's `coverFile`. `first` only sets it if the card has no cover yet, `last` always uses the newest image, `none` never sets it.
+- `createdAt`: `Date` (sent as an ISO timestamp)
+- `dependenciesEnabled`: `boolean`
+- `dueDateEnabled`: `boolean`
+- `effortScale`: `number[]`
+  The effort values the web app offers for a card. A card's `effort` may still be any other number.
+- `fallbackEffort`: `number` — **preview**
+  The effort the web app counts for cards without an `effort`, e.g. in charts, hero cards and run capacity.
+- `hideCompletedCardCountForDecks`: `boolean` — **preview**
+  `true` hides the number of done cards on decks in the web app.
+- `id`: `AccountId`
+- `maxHandSlotCount`: `number` — **preview**
+  How many cards that aren't done each user may have in their Hand, between 7 and 28. `handQueue/addCardsToHand`, `handQueue/setCardOrders` and `cards/create` with `putInQueue` fail beyond it. Starting a card and hand sync can still go beyond it.
+- `milestonesEnabled`: `boolean`
+- `name`: `string`
+- `priorityLabels`: `{a: string; b: string; c: string}`
+  The names the web app shows for the card priorities `a`, `b` and `c`.
+- `sprintsEnabled`: `boolean`
+  Whether the organization uses runs.
+- `startWeekday`: [`StartWeekday`](../types.md#startweekday)
+  The first day of the week in the calendar and timeline. Users can override it for themselves.
+- `statusChangeDurations`: `{snooze: number; archive: number | null}` — **preview**
+  In seconds. A started card without changes for `snooze` seconds becomes `snoozing`. A done card without changes and open comment threads for `archive` seconds gets archived. `archive` is `null` when done cards never get archived.
+- `subdomain`: `string`
+  The part before `.codecks.io` in the organization's web address.
+- `timeTrackingMode`: [`TimeTrackingMode`](../types.md#timetrackingmode) — **preview**
+  `none` turns time tracking off. `manual` allows only manual time entries. `strict` also adds a timer that users start with the play button on a card.
+- `timelineScaleType`: [`TimelineScaleType`](../types.md#timelinescaletype) — **preview**
+  Whether the timeline shows days or weeks. Users can override it for themselves.
+- `visionBoardEnabled`: `boolean` — **preview**
+- `workdays`: [`Workdays`](../types.md#workdays)
+  The days the team works. The web app only counts these days, e.g. for the days left until a milestone.
+- `workflowMode`: [`WorkflowMode`](../types.md#workflowmode) — **preview**
+  `journeys` when the organization uses journeys, `only_parent_cards` when not.
 
 ## Relations
 
-### belongsTo
-
-- `disabledBy` → [user](user.md) (via `disabledById`)
-
-### hasOne
-
-- `githubIntegration` → [integration](integration.md)
-- `slackIntegration` → [integration](integration.md)
-- `stripeAccountSync` → [stripeAccountSync](stripeAccountSync.md)
-- `accountOnboarding` → [accountOnboarding](accountOnboarding.md)
-
 ### hasMany
 
-- `cards` → [card](card.md)
-- `invoices` → [invoice](invoice.md)
-- `cardPresets` → [cardPreset](cardPreset.md)
+- `archivedProjects` → [project](project.md)
 - `attachments` → [attachment](attachment.md)
-- `discordGuilds` → [discordGuild](discordGuild.md)
-- `timeTrackingSegments` → [timeTrackingSegment](timeTrackingSegment.md)
-- `workflowItems` → [workflowItem](workflowItem.md)
-- `deckAssignments` → [deckAssignment](deckAssignment.md)
-- `assigneeAssignments` → [assigneeAssignment](assigneeAssignment.md)
-- `assigneeDeckAssignments` → [assigneeDeckAssignment](assigneeDeckAssignment.md)
-- `wizards` → [wizard](wizard.md)
-- `milestones` → [milestone](milestone.md)
-- `sprints` → [sprint](sprint.md)
-- `sprintConfigs` → [sprintConfig](sprintConfig.md)
-- `handCards` → [handCard](handCard.md)
-- `resolvables` → [resolvable](resolvable.md)
-- `cardUpvotes` → [cardUpvote](cardUpvote.md)
-- `resolvableParticipants` → [resolvableParticipant](resolvableParticipant.md)
-- `userReportSettings` → [userReportSetting](userReportSetting.md)
-- `cardOrders` → [cardOrder](cardOrder.md)
-- `accountUserAchievements` → [accountUserAchievement](accountUserAchievement.md)
-- `userInviteCodes` → [userInviteCode](userInviteCode.md)
-- `visionBoards` → [visionBoard](visionBoard.md)
-- `deckSubscriptions` → [deckSubscription](deckSubscription.md)
-- `appInstallations` → [appInstallation](appInstallation.md)
-- `files` → [file](file.md)
+- `cards` → [card](card.md)
 - `decks` → [deck](deck.md)
-- `queueEntries` → [queueEntry](queueEntry.md)
-- `visionBoardQueries` → [visionBoardQuery](visionBoardQuery.md)
-- `anyDecks` → [deck](deck.md)
+  Without deleted decks.
+- `files` → [file](file.md)
+- `handCards` → [handCard](handCard.md)
+  The bookmarked cards of all users.
+- `milestones` → [milestone](milestone.md)
 - `projects` → [project](project.md)
-- `archivedProjects` → [project](project.md)
-- `anyProjects` → [project](project.md)
-- `roles` → [accountRole](accountRole.md)
-- `invitations` → [userInvitation](userInvitation.md)
-- `affiliateCodes` → [affiliateCode](affiliateCode.md)
-- `activities` → [activity](activity.md)
+  Projects that are neither archived nor deleted.
+- `queueEntries` → [queueEntry](queueEntry.md)
+  The cards in the Card Hand of all users.
+- `resolvables` → [resolvable](resolvable.md)
+  The comment threads of all cards.
+- `sprintConfigs` → [sprintConfig](sprintConfig.md)
+  The organization's run configs.
+- `sprints` → [sprint](sprint.md)
+  The organization's runs.
+- `workflowItems` → [workflowItem](workflowItem.md) — **preview**
+  The organization's journey steps.

package/schema/models/attachment.md

@@ -1,23 +1,27 @@
 # attachment
 
+A file attached to a card.
+
 Key: `id`
 
 ## Fields
 
-- `id`: string
-- `content`: string
-- `title`: string
-- `createdAt`: Date (ISO string)
-- `fileId`: string (foreign key ID) → file
-- `cardId`: string (foreign key ID) → card
-- `accountId`: string (foreign key ID) → account
-- `creatorId`: string (foreign key ID) → user
+- `accountId`: [`AccountId`](account.md), foreign key of `account`
+- `cardId`: [`CardId`](card.md), foreign key of `card`
+- `content`: `string`
+  The attachment's label as markdown. It starts as the file name.
+- `createdAt`: `Date` (sent as an ISO timestamp)
+- `creatorId`: [`UserId`](user.md)` | null`, foreign key of `creator`
+- `fileId`: [`FileId`](file.md), foreign key of `file`
+- `id`: `AttachmentId`
+- `title`: `string`
+  The first line of `content` as plain text, cut to 80 characters.
 
 ## Relations
 
 ### belongsTo
 
-- `file` → [file](file.md) (via `fileId`)
-- `card` → [card](card.md) (via `cardId`)
 - `account` → [account](account.md) (via `accountId`)
-- `creator` → [user](user.md) (via `creatorId`)
+- `card` → [card](card.md) (via `cardId`)
+- `creator` → [user](user.md) (via `creatorId`), optional
+- `file` → [file](file.md) (via `fileId`)

package/schema/models/card.md

@@ -1,82 +1,108 @@
 # card
 
+A task or a document card when `isDoc` is set or a hero card if it contains sub cards.
+The card's color is derived from `status`, `visibility`, `isDoc` and whether it has sub cards or open block or review conversations.
+
 Key: `cardId`
 
 ## Fields
 
-- `cardId`: string
-- `version`: number
-- `accountSeq`: number
-- `content`: string
-- `status`: string
-- `derivedStatus`: string
-- `createdAt`: Date (ISO string)
-- `lastUpdatedAt`: Date (ISO string)
-- `tags`: array
-- `masterTags`: array
-- `mentionedUsers`: array
-- `title`: string
-- `priority`: string, optional
-- `effort`: number, optional
-- `checkboxStats`: object
-- `checkboxInfo`: array
-- `visibility`: string
-- `legacyProjectSeq`: number, optional
-- `meta`: object
-- `embeds`: object
-- `isPublic`: boolean
-- `hasBlockingDeps`: boolean
-- `dueDate`: {year, month, day}, optional
-- `isDoc`: boolean, optional
-- `childCardInfo`: string
-- `accountId`: string (foreign key ID) → account
-- `deckId`: string (foreign key ID) → deck, optional
-- `assigneeId`: string (foreign key ID) → user, optional
-- `creatorId`: string (foreign key ID) → user, optional
-- `milestoneId`: string (foreign key ID) → milestone, optional
-- `sprintId`: string (foreign key ID) → sprint, optional
-- `legacyProjectId`: string (foreign key ID) → project, optional
-- `coverFileId`: string (foreign key ID) → file, optional
-- `parentCardId`: string (foreign key ID) → card, optional
-- `sourceWorkflowItemId`: string (foreign key ID) → workflowItem, optional
-- `discordGuildId`: string (foreign key ID) → discordGuild
-- `visionBoardId`: string (foreign key ID) → visionBoard, optional
+- `accountId`: [`AccountId`](account.md), foreign key of `account`
+- `accountSeq`: `number`
+  The card's number within the organization. It's stored as a plain number starting at 1. The web app shows it encoded as a short code after a `$`, like `$12a`. Check [this gist](https://gist.github.com/danielberndt/19857421171dbb07a3681f0ea6634049) for how to translate the number into the shown string and vice versa.
+- `assigneeId`: [`UserId`](user.md)` | null`, foreign key of `assignee`
+  The card's owner.
+- `cardId`: `CardId`
+- `checkboxInfo`: [`Checkbox`](../types.md#checkbox)`[]` — **preview**
+  The checkboxes in `content`, in order.
+- `checkboxStats`: [`CheckboxStats`](../types.md#checkboxstats)
+  How many checkboxes `content` has, and how many of them are checked.
+- `content`: `string`
+  The card's text as markdown. Its first line is the `title`. Tags, mentions, checkboxes and card references in it fill `tags`, `masterTags`, `mentionedUsers`, `checkboxStats`, `checkboxInfo` and `cardReferences`.
+- `coverFileId`: [`FileId`](file.md)` | null`, foreign key of `coverFile`
+  The image shown on the card's front.
+- `createdAt`: `Date` (sent as an ISO timestamp)
+- `creatorId`: [`UserId`](user.md)` | null`, foreign key of `creator`
+  `null` for cards an import created.
+- `deckId`: [`DeckId`](deck.md)` | null`, foreign key of `deck`
+  `null` for a private card, which only its creator sees.
+- `derivedStatus`: [`DerivedStatus`](../types.md#derivedstatus) — **preview**
+  The state the web app shows, combining `status`, `visibility`, `isDoc`, open review and blocker threads, the assignee and whether it's a hero card: e.g. `blocked` for an open blocker thread, `unassigned` for a not started card without an assignee.
+- `dueDate`: `{year: number; month: number; day: number} | null` (sent as `YYYY-MM-DD`)
+- `effort`: `number | null`
+  On the organization's scale, `account.effortScale`.
+- `hasBlockingDeps`: `boolean` — **preview**
+  One of `inDeps` isn't done yet.
+- `isBlockingDep`: `boolean` — **preview**
+  The card isn't done yet, and one of its `outDeps` isn't either.
+- `isDoc`: `boolean | null`
+  `true` for a document card: it holds information instead of a task, so it's never started or done.
+- `lastUpdatedAt`: `Date` (sent as an ISO timestamp)
+  When the card last changed.
+- `masterTags`: `string[]`
+  The card's project tags: the tags from the project's tag list, whether written as `#tag` in `content` or set directly, plus the deck's auto-tag. Writing them may change `content`.
+- `mentionedUsers`: [`UserId`](user.md)`[]` — **preview**
+  The users mentioned in `content`.
+- `milestoneId`: [`MilestoneId`](milestone.md)` | null`, foreign key of `milestone`
+- `parentCardId`: `CardId | null`, foreign key of `parentCard`
+  The hero card this card is a sub card of.
+- `priority`: [`Priority`](../types.md#priority)` | null`
+  `a`, `b` or `c`: High, Medium and Low, unless the organization renamed them (`account.priorityLabels`).
+- `sourceWorkflowItemId`: [`WorkflowItemId`](workflowItem.md)` | null`, foreign key of `sourceWorkflowItem` — **preview**
+  The journey step the card was created from.
+- `sprintId`: [`SprintId`](sprint.md)` | null`, foreign key of `sprint`
+  The run the card is planned into.
+- `status`: `"not_started" | "started" | "snoozing" | "done" | (string & {})`
+  `snoozing` is only set on a `started` card that nobody changed for the organization's snooze time (`account.statusChangeDurations`). It can't be written. `derivedStatus` is the state the web app shows.
+- `tags`: `string[]`
+  Every tag on the card: the `#tags` in `content` and the `masterTags`, each once.
+- `title`: `string`
+  The first line of `content` as plain text, without markdown and cut to 80 characters. Write `content` to change it.
+- `version`: `number`
+  Goes up with every change to the card.
+- `visibility`: [`CardVisibility`](../types.md#cardvisibility)
+  `archived` cards are put away, `deleted` ones are in the trash. Both stay readable.
 
 ## Relations
 
 ### belongsTo
 
 - `account` → [account](account.md) (via `accountId`)
-- `deck` → [deck](deck.md) (via `deckId`)
-- `assignee` → [user](user.md) (via `assigneeId`)
-- `creator` → [user](user.md) (via `creatorId`)
-- `milestone` → [milestone](milestone.md) (via `milestoneId`)
-- `sprint` → [sprint](sprint.md) (via `sprintId`)
-- `legacyProject` → [project](project.md) (via `legacyProjectId`)
-- `coverFile` → [file](file.md) (via `coverFileId`)
-- `parentCard` → [card](card.md) (via `parentCardId`)
-- `sourceWorkflowItem` → [workflowItem](workflowItem.md) (via `sourceWorkflowItemId`)
-- `discordGuild` → [discordGuild](discordGuild.md) (via `discordGuildId`)
-- `visionBoard` → [visionBoard](visionBoard.md) (via `visionBoardId`)
-
-### hasOne
-
-- `totalTimeTrackingSums` → [timeTrackingSum](timeTrackingSum.md)
+- `assignee` → [user](user.md) (via `assigneeId`), optional
+  The card's owner.
+- `coverFile` → [file](file.md) (via `coverFileId`), optional
+  The image shown on the card's front.
+- `creator` → [user](user.md) (via `creatorId`), optional
+  `null` for cards an import created.
+- `deck` → [deck](deck.md) (via `deckId`), optional
+  `null` for a private card, which only its creator sees.
+- `milestone` → [milestone](milestone.md) (via `milestoneId`), optional
+- `parentCard` → [card](card.md) (via `parentCardId`), optional
+  The hero card this card is a sub card of.
+- `sourceWorkflowItem` → [workflowItem](workflowItem.md) (via `sourceWorkflowItemId`), optional — **preview**
+  The journey step the card was created from.
+- `sprint` → [sprint](sprint.md) (via `sprintId`), optional
+  The run the card is planned into.
 
 ### hasMany
 
-- `resolvables` → [resolvable](resolvable.md)
-- `handCards` → [handCard](handCard.md)
-- `timeTrackingSegments` → [timeTrackingSegment](timeTrackingSegment.md)
-- `cardSubscriptions` → [cardSubscription](cardSubscription.md)
-- `cardOrders` → [cardOrder](cardOrder.md)
-- `resolvableEntries` → [resolvableEntry](resolvableEntry.md)
-- `queueEntries` → [queueEntry](queueEntry.md)
 - `attachments` → [attachment](attachment.md) — `fkAsArray` (plain selection + `count`/`exists` only; no `filter`/`orderBy`/`limit`/`offset`/`first`)
-- `diffs` → [cardHistory](cardHistory.md)
-- `userTimeTrackingSums` → [timeTrackingSum](timeTrackingSum.md)
+  In the order the card shows them.
+- `cardReferences` → [card](card.md) — `fkAsArray` (plain selection + `count`/`exists` only; no `filter`/`orderBy`/`limit`/`offset`/`first`) — **preview**
+  The cards that `content` links to.
 - `childCards` → [card](card.md) — `fkAsArray` (plain selection + `count`/`exists` only; no `filter`/`orderBy`/`limit`/`offset`/`first`)
-- `inDeps` → [card](card.md) — `fkAsArray` (plain selection + `count`/`exists` only; no `filter`/`orderBy`/`limit`/`offset`/`first`)
-- `outDeps` → [card](card.md) — `fkAsArray` (plain selection + `count`/`exists` only; no `filter`/`orderBy`/`limit`/`offset`/`first`)
-- `cardReferences` → [card](card.md) — `fkAsArray` (plain selection + `count`/`exists` only; no `filter`/`orderBy`/`limit`/`offset`/`first`)
-- `upvotes` → [cardUpvote](cardUpvote.md)
+  A hero card's sub cards, in order.
+- `diffs` → [cardHistory](cardHistory.md) — **preview**
+  The card's change history.
+- `handCards` → [handCard](handCard.md)
+  One entry per user who bookmarked the card.
+- `inDeps` → [card](card.md) — `fkAsArray` (plain selection + `count`/`exists` only; no `filter`/`orderBy`/`limit`/`offset`/`first`) — **preview**
+  The cards that have to be done before this one.
+- `outDeps` → [card](card.md) — `fkAsArray` (plain selection + `count`/`exists` only; no `filter`/`orderBy`/`limit`/`offset`/`first`) — **preview**
+  The cards that wait for this one. The counterpart of their `inDeps`.
+- `queueEntries` → [queueEntry](queueEntry.md)
+  One entry per user who has the card in their Card Hand.
+- `resolvableEntries` → [resolvableEntry](resolvableEntry.md)
+  Every comment on the card, across its threads.
+- `resolvables` → [resolvable](resolvable.md)
+  The card's comment threads, including reviews and blockers (`context`).

package/schema/models/cardHistory.md

@@ -1,20 +1,26 @@
 # cardHistory
 
+One version of a card and what changed in it. The web app shows these in the card's history.
+
+**preview**: this model may change in any release. Each change is listed in the [API changelog](https://manual.codecks.io/api-changelog/).
+
 Key: `cardId`, `version`
 
 ## Fields
 
-- `diff`: object
-- `versionCreatedAt`: Date (ISO string)
-- `version`: number
-- `accountId`: string (foreign key ID) → account
-- `cardId`: string (foreign key ID) → card
-- `changerId`: string (foreign key ID) → user
+- `accountId`: [`AccountId`](account.md), foreign key of `account` — **preview**
+- `cardId`: [`CardId`](card.md), foreign key of `card` — **preview**
+- `changerId`: [`UserId`](user.md)` | null`, foreign key of `changer` — **preview**
+- `diff`: `{[key: string]: unknown}` — **preview**
+  The changed fields: `[old, new]` for single values, `{"+": added, "-": removed}` for lists, and an encoded text diff for `content` and `title`.
+- `version`: `number` — **preview**
+  The card's `version` after this change.
+- `versionCreatedAt`: `Date` (sent as an ISO timestamp) — **preview**
 
 ## Relations
 
 ### belongsTo
 
-- `account` → [account](account.md) (via `accountId`)
-- `card` → [card](card.md) (via `cardId`)
-- `changer` → [user](user.md) (via `changerId`)
+- `account` → [account](account.md) (via `accountId`) — **preview**
+- `card` → [card](card.md) (via `cardId`) — **preview**
+- `changer` → [user](user.md) (via `changerId`), optional — **preview**

package/schema/models/deck.md

@@ -1,53 +1,58 @@
 # deck
 
+A list of cards within a project. `deckType` says which kind of cards it is meant for.
+
 Key: `id`
 
 ## Fields
 
-- `id`: string
-- `content`: string
-- `description`: string
-- `title`: string
-- `sortValue`: string
-- `preferredOrder`: string, optional
-- `coverColor`: string, optional
-- `isDeleted`: string
-- `accountSeq`: number
-- `spaceId`: number, optional
-- `defaultCard`: object
-- `isOnboardingDeck`: boolean
-- `handSyncEnabled`: string
-- `stickyDefaultProjectTag`: string
-- `manualOrderLabels`: string
-- `workflowItemOrderLabels`: string
-- `createdAt`: Date (ISO string)
-- `stats`: object
-- `hasGuardians`: string
-- `allowedCardTypes`: string
-- `projectId`: string (foreign key ID) → project
-- `accountId`: string (foreign key ID) → account
-- `milestoneId`: string (foreign key ID) → milestone, optional
-- `creatorId`: string (foreign key ID) → user
-- `coverFileId`: string (foreign key ID) → file, optional
-- `descriptionCoverFileId`: string (foreign key ID) → file, optional
-- `defaultProjectTagId`: string (foreign key ID) → projectTag, optional
+- `accountId`: [`AccountId`](account.md), foreign key of `account`
+- `accountSeq`: `number`
+  The deck's number within the organization. The web app uses it in the deck's URL, like `/decks/12-my-deck`.
+- `coverColor`: `string | null` — **preview**
+  A hex color like `#ff8800`.
+- `coverFileId`: [`FileId`](file.md)` | null`, foreign key of `coverFile` — **preview**
+- `createdAt`: `Date` (sent as an ISO timestamp)
+- `creatorId`: [`UserId`](user.md), foreign key of `creator`
+- `deckType`: `"task" | "hero" | "doc" | "mixed" | (string & {})`
+  The web app calls these Task (`task`), Asset (`hero`), Knowledge (`doc`) and Mixed (`mixed`) decks. Cards in a `hero` deck count as hero cards unless they are docs or sub cards. A started card that moves into a `hero` or `doc` deck goes back to `not_started`.
+- `defaultCard`: [`DefaultCard`](../types.md#defaultcard) — **preview**
+  The deck's Template Card. The web app fills in these values when you create a card in this deck. `cards/create` doesn't use them.
+- `defaultProjectTagId`: [`ProjectTagId`](projectTag.md)` | null`, foreign key of `defaultProjectTag`
+  The deck's auto tag. Cards that are created in or moved into the deck get this project tag.
+- `description`: `string`
+- `handSyncEnabled`: `boolean` — **preview**
+  Cards in this deck that have an assignee go into the assignee's Hand. This happens when a card is created, moved into the deck or gets a new assignee.
+- `hasGuardians`: `boolean` — **preview**
+  The deck has [guardians](https://manual.codecks.io/guardians/). Then only guardians, producers and admins may mark its cards as done or not done, archive, delete, restore or move them.
+- `id`: `DeckId`
+- `isDeleted`: `boolean`
+- `manualOrderLabels`: `(string | null)[]` — **preview**
+  The names of the zones in the deck's manual order, in order. `null` is a zone without a name. A card's zone is the `label` of its `cardOrder` in the `deck` context.
+- `milestoneId`: [`MilestoneId`](milestone.md)` | null`, foreign key of `milestone`
+  Setting it also puts the deck's cards into this milestone.
+- `projectId`: [`ProjectId`](project.md), foreign key of `project`
+- `sortValue`: `string` — **preview**
+  Decks within a space are sorted by it. Change it with `decks/addToSpaceAfter` or `decks/addToSpaceBefore`.
+- `spaceId`: `number | null` — **preview**
+  The space of the project the deck is in, one of the ids in `project.spaces`.
+- `title`: `string`
 
 ## Relations
 
 ### belongsTo
 
-- `project` → [project](project.md) (via `projectId`)
 - `account` → [account](account.md) (via `accountId`)
-- `milestone` → [milestone](milestone.md) (via `milestoneId`)
+- `coverFile` → [file](file.md) (via `coverFileId`), optional — **preview**
 - `creator` → [user](user.md) (via `creatorId`)
-- `coverFile` → [file](file.md) (via `coverFileId`)
-- `descriptionCoverFile` → [file](file.md) (via `descriptionCoverFileId`)
-- `defaultProjectTag` → [projectTag](projectTag.md) (via `defaultProjectTagId`)
+- `defaultProjectTag` → [projectTag](projectTag.md) (via `defaultProjectTagId`), optional
+  The deck's auto tag. Cards that are created in or moved into the deck get this project tag.
+- `milestone` → [milestone](milestone.md) (via `milestoneId`), optional
+  Setting it also puts the deck's cards into this milestone.
+- `project` → [project](project.md) (via `projectId`)
 
 ### hasMany
 
 - `cards` → [card](card.md)
-- `workflowItems` → [workflowItem](workflowItem.md)
-- `cardOrderInDecks` → [cardOrderInDeck](cardOrderInDeck.md)
-- `activities` → [activity](activity.md)
-- `guardians` → [deckGuardian](deckGuardian.md)
+- `workflowItems` → [workflowItem](workflowItem.md) — **preview**
+  The steps of the deck's journey.

package/schema/models/file.md

@@ -1,26 +1,24 @@
 # file
 
+An uploaded file, like a card attachment or a cover image.
+
 Key: `id`
 
 ## Fields
 
-- `id`: string
-- `name`: string
-- `url`: string
-- `size`: string
-- `isDeleted`: string
-- `meta`: object
-- `createdAt`: Date (ISO string)
-- `deletedAt`: Date (ISO string)
-- `selfHosted`: string
-- `accountId`: string (foreign key ID) → account
-- `uploaderId`: string (foreign key ID) → user
-- `deletedById`: string (foreign key ID) → user
+- `accountId`: [`AccountId`](account.md)` | null`, foreign key of `account`
+- `createdAt`: `Date` (sent as an ISO timestamp)
+- `id`: `FileId`
+- `name`: `string`
+- `size`: `number`
+  In bytes. `0` once the file is deleted.
+- `uploaderId`: [`UserId`](user.md)` | null`, foreign key of `uploader`
+- `url`: `string`
+  Where to download the file. `""` once the file is deleted.
 
 ## Relations
 
 ### belongsTo
 
-- `account` → [account](account.md) (via `accountId`)
-- `uploader` → [user](user.md) (via `uploaderId`)
-- `deletedBy` → [user](user.md) (via `deletedById`)
+- `account` → [account](account.md) (via `accountId`), optional
+- `uploader` → [user](user.md) (via `uploaderId`), optional

package/schema/models/handCard.md

@@ -1,18 +1,21 @@
 # handCard
 
+A card a user bookmarked. Deleting the card removes its bookmarks.
+
 Key: `cardId`, `userId`, `accountId`
 
 ## Fields
 
-- `sortIndex`: number
-- `userId`: string (foreign key ID) → user
-- `accountId`: string (foreign key ID) → account
-- `cardId`: string (foreign key ID) → card
+- `accountId`: [`AccountId`](account.md), foreign key of `account`
+- `cardId`: [`CardId`](card.md), foreign key of `card`
+- `sortIndex`: `number`
+  Bookmarks are listed by ascending `sortIndex`. There may be gaps.
+- `userId`: [`UserId`](user.md), foreign key of `user`
 
 ## Relations
 
 ### belongsTo
 
-- `user` → [user](user.md) (via `userId`)
 - `account` → [account](account.md) (via `accountId`)
 - `card` → [card](card.md) (via `cardId`)
+- `user` → [user](user.md) (via `userId`)