@dereekb/trello 13.11.14

package/src/lib/trello.error.api.d.ts

@@ -0,0 +1,77 @@
+import { type Maybe } from '@dereekb/util';
+import { type ConfiguredFetch, type FetchRequestFactoryError, FetchResponseError } from '@dereekb/util/fetch';
+import { BaseError } from 'make-error';
+/**
+ * Raw error body shape returned by the Trello API.
+ *
+ * Trello commonly returns a plain text body (e.g. "invalid token") rather than JSON.
+ * This shape captures both the parsed JSON case and the text fallback.
+ */
+export interface TrelloServerErrorData {
+    /**
+     * Status code of the underlying HTTP response.
+     */
+    readonly status: number;
+    /**
+     * Raw response body as text. Always present.
+     */
+    readonly bodyText: string;
+    /**
+     * Parsed JSON body when the response had a JSON content type.
+     */
+    readonly bodyJson?: unknown;
+}
+/**
+ * Base Trello server error.
+ */
+export declare class TrelloServerError extends BaseError {
+    readonly data: TrelloServerErrorData;
+    constructor(message: string, data: TrelloServerErrorData);
+    get status(): number;
+}
+/**
+ * Trello server error that retains the originating fetch response.
+ */
+export declare class TrelloServerFetchResponseError extends TrelloServerError {
+    readonly responseError: FetchResponseError;
+    constructor(message: string, data: TrelloServerErrorData, responseError: FetchResponseError);
+}
+/**
+ * Trello returned 401 — typically a revoked or otherwise invalid token.
+ *
+ * @see https://developer.atlassian.com/cloud/trello/guides/rest-api/authorization/
+ */
+export declare class TrelloInvalidTokenError extends TrelloServerFetchResponseError {
+}
+/**
+ * Trello returned 429 — too many requests.
+ */
+export declare class TrelloTooManyRequestsError extends TrelloServerFetchResponseError {
+    get retryAfter(): Maybe<number>;
+}
+export type LogTrelloServerErrorFunction = (error: FetchRequestFactoryError | TrelloServerError) => void;
+/**
+ * Creates a logTrelloServerErrorFunction that logs the error to console.
+ *
+ * @param trelloApiNamePrefix Prefix to use when logging.
+ * @returns A function that logs Trello server errors to the console.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function logTrelloServerErrorFunction(trelloApiNamePrefix: string): LogTrelloServerErrorFunction;
+export declare const logTrelloErrorToConsole: LogTrelloServerErrorFunction;
+/**
+ * Parses a FetchResponseError into a typed Trello API error.
+ *
+ * @param responseError The fetch response error to parse.
+ * @returns A typed Trello error, or undefined if the response could not be parsed.
+ */
+export declare function parseTrelloApiError(responseError: FetchResponseError): Promise<Maybe<TrelloServerFetchResponseError>>;
+/**
+ * Wraps a ConfiguredFetch to translate FetchResponseError into typed Trello errors.
+ *
+ * @param fetch The fetch to wrap.
+ * @param logError Optional logger.
+ * @returns A ConfiguredFetch that throws typed Trello errors for known error responses.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function handleTrelloErrorFetch(fetch: ConfiguredFetch, logError?: LogTrelloServerErrorFunction): ConfiguredFetch;

package/src/lib/trello.limit.d.ts

@@ -0,0 +1,40 @@
+import { type Maybe, type Milliseconds, type ResetPeriodPromiseRateLimiter } from '@dereekb/util';
+import { type RateLimitedFetchHandler } from '@dereekb/util/fetch';
+/**
+ * Documented per-token rate limit: 100 requests per 10 seconds.
+ *
+ * @see https://developer.atlassian.com/cloud/trello/guides/rest-api/rate-limits/
+ */
+export declare const DEFAULT_TRELLO_API_RATE_LIMIT = 100;
+/**
+ * Reset period for the per-token rate limit (10 seconds).
+ */
+export declare const DEFAULT_TRELLO_API_RATE_LIMIT_RESET_PERIOD: Milliseconds;
+export interface TrelloRateLimiterRef {
+    readonly trelloRateLimiter: ResetPeriodPromiseRateLimiter;
+}
+export interface TrelloRateLimitedFetchHandlerConfig {
+    /**
+     * Maximum number of requests allowed per reset period.
+     *
+     * Defaults to DEFAULT_TRELLO_API_RATE_LIMIT.
+     */
+    readonly maxRateLimit?: number;
+    /**
+     * Reset period for the rate limiter, in milliseconds.
+     *
+     * Defaults to DEFAULT_TRELLO_API_RATE_LIMIT_RESET_PERIOD.
+     */
+    readonly resetPeriod?: Milliseconds;
+}
+export type TrelloRateLimitedFetchHandler = RateLimitedFetchHandler<ResetPeriodPromiseRateLimiter>;
+/**
+ * Creates a rate-limited fetch handler configured for the Trello API.
+ *
+ * Backs off after 429 responses and respects the documented per-token rate limit.
+ *
+ * @param config Optional configuration for rate limiting behavior.
+ * @returns A configured rate-limited fetch handler.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function trelloRateLimitedFetchHandler(config?: Maybe<TrelloRateLimitedFetchHandlerConfig>): TrelloRateLimitedFetchHandler;

package/src/lib/trello.type.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 24-character hex id used for boards, lists, cards, members, webhooks, etc.
+ */
+export type TrelloId = string;
+export type TrelloBoardId = TrelloId;
+export type TrelloListId = TrelloId;
+export type TrelloCardId = TrelloId;
+export type TrelloMemberId = TrelloId;
+export type TrelloLabelId = TrelloId;
+export type TrelloActionId = TrelloId;
+export type TrelloChecklistId = TrelloId;
+export type TrelloWebhookId = TrelloId;
+export type TrelloOrganizationId = TrelloId;
+export type TrelloEnterpriseId = TrelloId;
+/**
+ * Trello API key, exposed publicly as part of Power-Up configuration.
+ */
+export type TrelloApiKey = string;
+/**
+ * Trello user API token granted via the OAuth1 or `/1/authorize` flow.
+ *
+ * Treat as a secret — token grants the same access the user has consented to.
+ */
+export type TrelloApiToken = string;
+/**
+ * Application secret used to sign webhook requests for verification.
+ *
+ * Found on the same Power-Up admin page as the API key.
+ */
+export type TrelloAppSecret = string;
+/**
+ * Trello username (the slug portion of a profile URL).
+ */
+export type TrelloUsername = string;
+/**
+ * Trello API URL (versioned).
+ */
+export declare const TRELLO_API_URL = "https://api.trello.com/1";
+export type TrelloApiUrl = typeof TRELLO_API_URL;