/** * @fileoverview Shared Trello types: `JsonRecord`, `TrelloAuthMode`, `TrelloAuthInput`, `MutationInput`, `DryRunResult`, `TrelloPageInfo`, `TrelloMemberSummary`, `TrelloOrganizationSummary`, and related shapes. * Import from `kody:@kody/trello/types` when typing Trello helpers. Default export returns a type-name catalog. * * @example * import { type TrelloAuthMode } from 'kody:@kody/trello/types' */ export type JsonRecord = Record export type TrelloAuthMode = 'oauth' | 'keyToken' export type TrelloAuthInput = { /** Saved OAuth integration name. Defaults to `trello`. */ integrationName?: string /** Alias of `integrationName`. */ integration?: string /** * Short account alias. `work` → `trello-work`. Values that already start * with `trello-` are used as-is. `default` / `trello` / omitted → `trello`. */ account?: string /** User secret name for the Trello user token. Defaults to `trelloToken`. */ secretName?: string /** User secret name for the Trello API key. Defaults to `trelloApiKey`. */ apiKeySecretName?: string /** Force OAuth or API-key+token auth when both exist. */ auth?: TrelloAuthMode } export type MutationInput = { confirm?: boolean dryRun?: boolean } export type DryRunResult = { dryRun: true method: string path: string body?: T } export type TrelloPageInfo = { hasNextPage: boolean before: string | null } export type TrelloMemberSummary = { id: string username: string | null fullName: string | null url: string | null initials: string | null } export type TrelloOrganizationSummary = { id: string name: string | null displayName: string | null url: string | null } export type TrelloBoardSummary = { id: string name: string desc: string | null closed: boolean | null url: string | null shortUrl: string | null shortLink: string | null idOrganization: string | null dateLastActivity: string | null } export type TrelloListSummary = { id: string name: string closed: boolean | null idBoard: string | null pos: number | null } export type TrelloLabelSummary = { id: string name: string | null color: string | null } export type TrelloCardSummary = { id: string name: string desc: string | null closed: boolean | null idList: string | null idBoard: string | null url: string | null shortUrl: string | null due: string | null dueComplete: boolean | null pos: number | null idMembers: Array labels: Array dateLastActivity: string | null } export type TrelloCommentSummary = { id: string text: string | null date: string | null cardId: string | null memberCreator: TrelloMemberSummary | null } /** * Shared Trello types and parsing helpers for this package. * Import from `kody:@kody/trello/types` when typing other Trello exports. * * @returns Catalog of exported type/helper names for agent discovery. * * @example * import types from 'kody:@kody/trello/types' * const catalog = await types() */ export function requireRecord(value: unknown, label: string): JsonRecord { if (!value || typeof value !== 'object' || Array.isArray(value)) { throw new Error(`${label} must be an object.`) } return value as JsonRecord } export function requireString( value: unknown, label: string, options: { allowEmpty?: boolean } = {}, ): string { if (typeof value !== 'string' || (!options.allowEmpty && value.trim().length === 0)) { throw new Error( `${label} must be ${options.allowEmpty ? 'a string' : 'a non-empty string'}.`, ) } return options.allowEmpty ? value : value.trim() } export function optionalString(value: unknown, label: string): string | undefined { if (value === undefined || value === null) return undefined return requireString(value, label) } export function optionalBoolean(value: unknown, label: string): boolean | undefined { if (value === undefined) return undefined if (typeof value !== 'boolean') throw new Error(`${label} must be a boolean.`) return value } export function optionalNumber(value: unknown, label: string): number | undefined { if (value === undefined || value === null) return undefined if (typeof value !== 'number' || !Number.isFinite(value)) { throw new Error(`${label} must be a number.`) } return value } export function requireId(value: unknown, label: string): string { if (typeof value === 'number' && Number.isFinite(value)) return String(value) return requireString(value, label) } export function optionalStringArray(value: unknown, label: string): Array | undefined { if (value === undefined || value === null) return undefined if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) { throw new Error(`${label} must be an array of strings.`) } return value.map((item) => item.trim()).filter((item) => item.length > 0) } export function clampInt( value: unknown, min: number, max: number, fallback: number, label = 'limit', ): number { if (value === undefined || value === null) return fallback if (typeof value !== 'number' || !Number.isInteger(value)) { throw new Error(`${label} must be an integer.`) } if (value < min || value > max) { throw new Error(`${label} must be between ${min} and ${max}.`) } return value } export function compactRecord(value: T): T { const output: JsonRecord = {} for (const [key, item] of Object.entries(value)) { if (item === undefined) continue output[key] = item } return output as T } export function parseAction( value: unknown, allowed: ReadonlyArray, fallback: T, label: string, ): T { if (value === undefined || value === null || value === '') return fallback const action = requireString(value, 'action') if (!allowed.includes(action as T)) { throw new Error(`${label} action must be one of: ${allowed.join(', ')}.`) } return action as T } /** * Shared Trello types for this package: `JsonRecord`, `TrelloAuthMode`, `TrelloAuthInput`, `MutationInput`, `DryRunResult`, `TrelloPageInfo`, `TrelloMemberSummary`, `TrelloOrganizationSummary`, and related shapes. * Import from `kody:@kody/trello/types` when typing Trello helpers without pulling runtime clients. * * @returns Catalog of exported type names for agent discovery. * * @example * import types from 'kody:@kody/trello/types' * const catalog = await types() */ export default async function typesOverview() { return { auth: ['TrelloAuthInput', 'TrelloAuthMode'], models: [ 'TrelloBoardSummary', 'TrelloListSummary', 'TrelloCardSummary', 'TrelloCommentSummary', 'TrelloMemberSummary', ], } }