@codecks/fetch 0.1.5 → 0.1.6

package/schema/models/visionBoardQuery.md

@@ -0,0 +1,22 @@
+# visionBoardQuery
+
+Key: `id`
+
+## Fields
+
+- `id`: string
+- `query`: object
+- `lastUsedAt`: Date (ISO string)
+- `isStale`: boolean
+- `type`: string
+- `payload`: object
+- `createdAt`: Date (ISO string)
+- `cardId`: string (foreign key ID) → card
+- `accountId`: string (foreign key ID) → account
+
+## Relations
+
+### belongsTo
+
+- `card` → [card](card.md) (via `cardId`)
+- `account` → [account](account.md) (via `accountId`)

package/schema/models/wizard.md

@@ -0,0 +1,19 @@
+# wizard
+
+Key: `id`
+
+## Fields
+
+- `id`: string
+- `name`: string
+- `currentStep`: string
+- `data`: object
+- `createdAt`: Date (ISO string)
+- `finishedAt`: Date (ISO string)
+- `accountId`: string (foreign key ID) → account
+
+## Relations
+
+### belongsTo
+
+- `account` → [account](account.md) (via `accountId`)

package/schema/models/workflowItem.md

@@ -0,0 +1,45 @@
+# workflowItem
+
+Key: `itemId`
+
+## Fields
+
+- `itemId`: string
+- `version`: string
+- `sortOrder`: string
+- `sortValue`: string
+- `priority`: string, optional
+- `content`: string
+- `createdAt`: Date (ISO string)
+- `lastUpdatedAt`: Date (ISO string)
+- `tags`: array
+- `masterTags`: array
+- `mentionedUsers`: array
+- `title`: string
+- `effort`: number, optional
+- `label`: string, optional
+- `checkboxStats`: object
+- `accountSeq`: number
+- `checkboxInfo`: array
+- `visibility`: string
+- `accountId`: string (foreign key ID) → account
+- `deckId`: string (foreign key ID) → deck
+- `targetDeckId`: string (foreign key ID) → deck, optional
+- `assigneeId`: string (foreign key ID) → user, optional
+- `creatorId`: string (foreign key ID) → user
+
+## Relations
+
+### belongsTo
+
+- `account` → [account](account.md) (via `accountId`)
+- `deck` → [deck](deck.md) (via `deckId`)
+- `targetDeck` → [deck](deck.md) (via `targetDeckId`)
+- `assignee` → [user](user.md) (via `assigneeId`)
+- `creator` → [user](user.md) (via `creatorId`)
+
+### hasMany
+
+- `diffs` → [workflowItemHistory](workflowItemHistory.md)
+- `inDeps` → [workflowItem](workflowItem.md)
+- `outDeps` → [workflowItem](workflowItem.md)

package/schema/models/workflowItemHistory.md

@@ -0,0 +1,18 @@
+# workflowItemHistory
+
+Key: `itemId`, `version`
+
+## Fields
+
+- `diff`: object
+- `versionCreatedAt`: Date (ISO string)
+- `version`: number
+- `accountId`: string (foreign key ID) → account
+- `changerId`: string (foreign key ID) → user
+
+## Relations
+
+### belongsTo
+
+- `account` → [account](account.md) (via `accountId`)
+- `changer` → [user](user.md) (via `changerId`)

package/schema/overview.md

@@ -0,0 +1,110 @@
+# @codecks/fetch Schema Overview
+
+## Root Entry Points
+
+These relations are available when using `fetchFromRoot`:
+
+- `releases` (hasMany) → [release](models/release.md)
+- `accountOnboardingSteps` (hasMany) → [accountOnboardingStep](models/accountOnboardingStep.md)
+- `apps` (hasMany) → [app](models/app.md)
+- `account` (hasOne) → [account](models/account.md)
+- `loggedInUser` (hasOne) → [user](models/user.md)
+- `cardsStatusHistory` (hasMany) → [cardsStatusHistory](models/cardsStatusHistory.md)
+- `cardsEffortHistory` (hasMany) → [cardsEffortHistory](models/cardsEffortHistory.md)
+- `cardsFinishedHistory` (hasMany) → [cardsFinishedHistory](models/cardsFinishedHistory.md)
+- `cardsTimeToFinished` (hasMany) → [cardsTimeToFinished](models/cardsTimeToFinished.md)
+
+## All Models
+
+- [accountOnboardingStep](models/accountOnboardingStep.md) (key: key) — 8 fields, 0 relations
+- [accountOnboarding](models/accountOnboarding.md) (key: accountId) — 3 fields, 1 relations
+- [accountRole](models/accountRole.md) (key: accountId, userId) — 6 fields, 2 relations
+- [accountUserAchievement](models/accountUserAchievement.md) (key: accountId, userId, key) — 4 fields, 2 relations
+- [accountUserSetting](models/accountUserSetting.md) (key: accountId, userId) — 6 fields, 3 relations
+- [account](models/account.md) (key: id) — 45 fields, 42 relations
+- [activeTimeTracker](models/activeTimeTracker.md) (key: id) — 5 fields, 3 relations
+- [activity](models/activity.md) (key: id) — 13 fields, 6 relations
+- [affiliateCodeStat](models/affiliateCodeStat.md) (key: affiliateCodeId, month) — 7 fields, 1 relations
+- [affiliateCode](models/affiliateCode.md) (key: id) — 13 fields, 3 relations
+- [appInstallation](models/appInstallation.md) (key: id) — 5 fields, 3 relations
+- [app](models/app.md) (key: id) — 4 fields, 0 relations
+- [assigneeAssignment](models/assigneeAssignment.md) (key: assigneeId, assignedById) — 4 fields, 3 relations
+- [assigneeDeckAssignment](models/assigneeDeckAssignment.md) (key: assigneeId, assignedById, deckId) — 5 fields, 4 relations
+- [attachment](models/attachment.md) (key: id) — 8 fields, 4 relations
+- [autoFinishedTimeTrackingSegment](models/autoFinishedTimeTrackingSegment.md) (key: userId, accountId) — 5 fields, 4 relations
+- [cardDiffNotification](models/cardDiffNotification.md) (key: userId, cardId) — 8 fields, 3 relations
+- [cardHistory](models/cardHistory.md) (key: cardId, version) — 6 fields, 3 relations
+- [cardOrderInDeck](models/cardOrderInDeck.md) (key: cardId, deckId) — 4 fields, 3 relations
+- [cardOrder](models/cardOrder.md) (key: context, cardId) — 4 fields, 2 relations
+- [cardPreset](models/cardPreset.md) (key: id) — 6 fields, 2 relations
+- [cardSubscription](models/cardSubscription.md) (key: id) — 5 fields, 3 relations
+- [cardUpvote](models/cardUpvote.md) (key: id) — 7 fields, 3 relations
+- [card](models/card.md) (key: cardId) — 37 fields, 28 relations
+- [cardsEffortHistory](models/cardsEffortHistory.md) (key: date, effortSum, cardCount) — 3 fields, 0 relations
+- [cardsFinishedHistory](models/cardsFinishedHistory.md) (key: date, effortSum, cardCount, assigneeId) — 4 fields, 1 relations
+- [cardsStatusHistory](models/cardsStatusHistory.md) (key: date, status, count) — 3 fields, 0 relations
+- [cardsTimeToFinished](models/cardsTimeToFinished.md) (key: cardId, startedAt, doneAt, effort, assigneeId) — 5 fields, 2 relations
+- [dailyDiscordGuildVoteMembership](models/dailyDiscordGuildVoteMembership.md) (key: t, guildId) — 3 fields, 1 relations
+- [dailyPublicProjectMembership](models/dailyPublicProjectMembership.md) (key: t, projectId) — 3 fields, 1 relations
+- [publicProjectVisit](models/publicProjectVisit.md) (key: t, projectId) — 4 fields, 1 relations
+- [deckAssignment](models/deckAssignment.md) (key: userId, deckId) — 4 fields, 3 relations
+- [deckGuardian](models/deckGuardian.md) (key: deckId, userId) — 3 fields, 3 relations
+- [deckSubscription](models/deckSubscription.md) (key: id) — 4 fields, 3 relations
+- [deck](models/deck.md) (key: id) — 27 fields, 12 relations
+- [discordGuild](models/discordGuild.md) (key: id) — 11 fields, 5 relations
+- [discordMember](models/discordMember.md) (key: id) — 9 fields, 1 relations
+- [discordProjectNotification](models/discordProjectNotification.md) (key: id) — 6 fields, 2 relations
+- [discordSlashCommand](models/discordSlashCommand.md) (key: id) — 15 fields, 2 relations
+- [dueCard](models/dueCard.md) (key: userId, cardId) — 4 fields, 3 relations
+- [file](models/file.md) (key: id) — 12 fields, 3 relations
+- [handCard](models/handCard.md) (key: cardId, userId, accountId) — 4 fields, 3 relations
+- [integration](models/integration.md) (key: id) — 9 fields, 3 relations
+- [invoice](models/invoice.md) (key: id) — 9 fields, 1 relations
+- [lastSeenCardUpvote](models/lastSeenCardUpvote.md) (key: userId, accountId) — 4 fields, 2 relations
+- [milestoneProgress](models/milestoneProgress.md) (key: milestoneId, date) — 2 fields, 1 relations
+- [milestoneProject](models/milestoneProject.md) (key: milestoneId, projectId) — 3 fields, 3 relations
+- [milestone](models/milestone.md) (key: id) — 18 fields, 7 relations
+- [pinnedMilestone](models/pinnedMilestone.md) (key: id) — 7 fields, 4 relations
+- [projectOrder](models/projectOrder.md) (key: projectId, userId, accountId) — 4 fields, 3 relations
+- [projectSelection](models/projectSelection.md) (key: id) — 4 fields, 3 relations
+- [projectTag](models/projectTag.md) (key: id) — 7 fields, 1 relations
+- [projectUserSetting](models/projectUserSetting.md) (key: projectId, userId) — 2 fields, 2 relations
+- [projectUser](models/projectUser.md) (key: projectId, userId) — 4 fields, 3 relations
+- [project](models/project.md) (key: id) — 24 fields, 17 relations
+- [publicProjectInfo](models/publicProjectInfo.md) (key: projectId) — 7 fields, 2 relations
+- [publicProjectMembership](models/publicProjectMembership.md) (key: userId, projectId) — 4 fields, 2 relations
+- [queueEntry](models/queueEntry.md) (key: id) — 7 fields, 3 relations
+- [queueSelection](models/queueSelection.md) (key: id) — 5 fields, 3 relations
+- [release](models/release.md) (key: id) — 6 fields, 0 relations
+- [resolvableEntryHistory](models/resolvableEntryHistory.md) (key: entryId, version) — 6 fields, 3 relations
+- [resolvableEntryReaction](models/resolvableEntryReaction.md) (key: id) — 8 fields, 4 relations
+- [resolvableEntry](models/resolvableEntry.md) (key: entryId) — 9 fields, 5 relations
+- [resolvableNotification](models/resolvableNotification.md) (key: userId, resolvableId) — 14 fields, 5 relations
+- [resolvableParticipantHistory](models/resolvableParticipantHistory.md) (key: participantId, resolvableId, version) — 9 fields, 3 relations
+- [resolvableParticipant](models/resolvableParticipant.md) (key: participantId, resolvableId) — 10 fields, 4 relations
+- [resolvable](models/resolvable.md) (key: id) — 11 fields, 7 relations
+- [savedSearch](models/savedSearch.md) (key: id) — 5 fields, 2 relations
+- [sprintConfigProgress](models/sprintConfigProgress.md) (key: sprintConfigId, date) — 2 fields, 1 relations
+- [sprintConfig](models/sprintConfig.md) (key: id) — 19 fields, 5 relations
+- [sprintProgress](models/sprintProgress.md) (key: sprintId, date) — 2 fields, 1 relations
+- [sprintProject](models/sprintProject.md) (key: sprintConfigId, projectId) — 3 fields, 3 relations
+- [sprint](models/sprint.md) (key: id) — 20 fields, 8 relations
+- [stripeAccountSync](models/stripeAccountSync.md) (key: accountId) — 17 fields, 1 relations
+- [timeTrackingSegment](models/timeTrackingSegment.md) (key: id) — 10 fields, 3 relations
+- [timeTrackingSum](models/timeTrackingSum.md) (key: cardId, userId) — 5 fields, 2 relations
+- [userDismissedHint](models/userDismissedHint.md) (key: userId, hintKey) — 4 fields, 1 relations
+- [userEmail](models/userEmail.md) (key: id) — 6 fields, 1 relations
+- [userInvitation](models/userInvitation.md) (key: id) — 7 fields, 2 relations
+- [userInviteCode](models/userInviteCode.md) (key: id) — 10 fields, 2 relations
+- [userOnboarding](models/userOnboarding.md) (key: userId) — 2 fields, 1 relations
+- [userProjectAccess](models/userProjectAccess.md) (key: projectId, userId) — 4 fields, 2 relations
+- [userTag](models/userTag.md) (key: id) — 5 fields, 2 relations
+- [user](models/user.md) (key: id) — 19 fields, 31 relations
+- [userReportEmail](models/userReportEmail.md) (key: id) — 6 fields, 2 relations
+- [userReportSetting](models/userReportSetting.md) (key: id) — 7 fields, 2 relations
+- [userReportToken](models/userReportToken.md) (key: token) — 6 fields, 1 relations
+- [visionBoardQuery](models/visionBoardQuery.md) (key: id) — 9 fields, 2 relations
+- [visionBoard](models/visionBoard.md) (key: id) — 7 fields, 3 relations
+- [wizard](models/wizard.md) (key: id) — 7 fields, 1 relations
+- [workflowItemHistory](models/workflowItemHistory.md) (key: itemId, version) — 5 fields, 2 relations
+- [workflowItem](models/workflowItem.md) (key: itemId) — 23 fields, 8 relations

package/schema/query-syntax.md

@@ -0,0 +1,155 @@
+# Query Syntax Reference
+
+## Basic Query
+
+```ts
+const {fetchFromRoot, fetchInstance} = buildFetchersWithSimpleLoader({
+  token: "your-api-token",
+});
+
+// Fetch from root entry points
+const result = await fetchFromRoot({
+  account: {fields: ["name", "subdomain"]},
+});
+// result.account.name, result.account.subdomain
+
+// Fetch a specific instance by model + ID
+const card = await fetchInstance("card", cardId, {
+  fields: ["title", "status", "effort"],
+});
+// card.title, card.status, card.effort
+```
+
+## Field Selection
+
+`fields` is an array of field names to include in the response.
+Key fields (like `cardId` for card, `id` for most models) are always returned.
+The meta fields `~model` and `~key` are always included.
+
+```ts
+{fields: ["title", "status", "createdAt"]}
+```
+
+## Nested Relations
+
+Use `relations` to traverse the object graph:
+
+```ts
+const result = await fetchFromRoot({
+  account: {
+    fields: ["name"],
+    relations: {
+      cards: {
+        fields: ["title", "status"],
+        relations: {
+          assignee: {fields: ["name"]},
+          deck: {fields: ["title"]},
+        },
+      },
+    },
+  },
+});
+```
+
+## hasMany Variants
+
+hasMany relations support different query types:
+
+### Default (array)
+```ts
+{cards: {fields: ["title", "status"]}}
+// returns: cards: Array<{title, status, ...}>
+```
+
+### count
+```ts
+{cards: {type: "count", as: "cardCount"}}
+// returns: cardCount: number
+```
+
+### exists
+```ts
+{cards: {type: "exists", as: "hasCards"}}
+// returns: hasCards: boolean
+```
+
+### first
+```ts
+{cards: {type: "first", as: "latestCard", orderBy: "-createdAt", fields: ["title"]}}
+// returns: latestCard: {title, ...} | null
+```
+
+### Multiple variants of the same relation
+Pass an array of queries with `as` aliases:
+```ts
+{
+  cards: [
+    {as: "openCards", filter: {status: "started"}, fields: ["title"]},
+    {as: "cardCount", type: "count"},
+  ]
+}
+// returns: openCards: Array<...>, cardCount: number
+```
+
+## Filtering (hasMany only)
+
+```ts
+{
+  cards: {
+    fields: ["title"],
+    filter: {
+      status: "started",                          // exact match
+      effort: {op: "gte", value: 3},              // comparison: lt, lte, gt, gte
+      assigneeId: {op: "eq", value: userId},      // equality: eq, neq (supports null)
+      tags: {op: "has", value: "bug"},             // array contains
+      title: {op: "contains", value: "search"},   // string contains
+      priority: {op: "in", value: ["high", "critical"]},  // in set
+    },
+  },
+}
+```
+
+### Logical operators
+```ts
+{
+  cards: {
+    fields: ["title"],
+    filter: {
+      $or: [
+        {status: "started"},
+        {status: "done"},
+      ],
+    },
+  },
+}
+```
+
+### Filter by relation
+```ts
+{
+  cards: {
+    fields: ["title"],
+    filter: {
+      assignee: {name: "Alice"},           // cards where assignee.name = "Alice"
+      "!deck": {isDeleted: "true"},        // negated: cards NOT in deleted decks
+    },
+  },
+}
+```
+
+## Ordering (hasMany only)
+
+```ts
+// Simple: field name, prefix with - for descending
+{cards: {fields: ["title"], orderBy: "createdAt"}}
+{cards: {fields: ["title"], orderBy: "-createdAt"}}
+
+// Multiple
+{cards: {fields: ["title"], orderBy: ["status", "-createdAt"]}}
+```
+
+## Pagination (hasMany only)
+
+```ts
+{cards: {fields: ["title"], limit: 10, offset: 20}}
+```