quickbase-js 1.2.0 → 2.0.0-alpha.2

package/dist/core/errors.js

@@ -0,0 +1,185 @@
+/**
+ * Custom error types for the QuickBase SDK
+ */
+/**
+ * Base error class for all QuickBase SDK errors
+ */
+export class QuickbaseError extends Error {
+    statusCode;
+    description;
+    rayId;
+    constructor(message, statusCode, options) {
+        super(message, { cause: options?.cause });
+        this.name = 'QuickbaseError';
+        this.statusCode = statusCode;
+        this.description = options?.description;
+        this.rayId = options?.rayId;
+        // Maintains proper stack trace in V8 environments
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, QuickbaseError);
+        }
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            statusCode: this.statusCode,
+            description: this.description,
+            rayId: this.rayId,
+        };
+    }
+}
+/**
+ * Error thrown when rate limited (HTTP 429)
+ */
+export class RateLimitError extends QuickbaseError {
+    retryAfter;
+    rateLimitInfo;
+    constructor(rateLimitInfo, message) {
+        super(message || `Rate limited. Retry after ${rateLimitInfo.retryAfter ?? 'unknown'} seconds`, 429, { rayId: rateLimitInfo.qbApiRay || rateLimitInfo.cfRay });
+        this.name = 'RateLimitError';
+        this.retryAfter = rateLimitInfo.retryAfter;
+        this.rateLimitInfo = rateLimitInfo;
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            retryAfter: this.retryAfter,
+            rateLimitInfo: this.rateLimitInfo,
+        };
+    }
+}
+/**
+ * Error thrown when authentication fails (HTTP 401)
+ */
+export class AuthenticationError extends QuickbaseError {
+    constructor(message, options) {
+        super(message, 401, options);
+        this.name = 'AuthenticationError';
+    }
+}
+/**
+ * Error thrown when authorization fails (HTTP 403)
+ */
+export class AuthorizationError extends QuickbaseError {
+    constructor(message, options) {
+        super(message, 403, options);
+        this.name = 'AuthorizationError';
+    }
+}
+/**
+ * Error thrown when a resource is not found (HTTP 404)
+ */
+export class NotFoundError extends QuickbaseError {
+    constructor(message, options) {
+        super(message, 404, options);
+        this.name = 'NotFoundError';
+    }
+}
+/**
+ * Error thrown for bad requests (HTTP 400)
+ */
+export class ValidationError extends QuickbaseError {
+    errors;
+    constructor(message, options) {
+        super(message, 400, options);
+        this.name = 'ValidationError';
+        this.errors = options?.errors;
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            errors: this.errors,
+        };
+    }
+}
+/**
+ * Error thrown when request times out
+ */
+export class TimeoutError extends QuickbaseError {
+    timeoutMs;
+    constructor(timeoutMs, options) {
+        super(`Request timed out after ${timeoutMs}ms`, 0, options);
+        this.name = 'TimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            timeoutMs: this.timeoutMs,
+        };
+    }
+}
+/**
+ * Error thrown for server errors (HTTP 5xx)
+ */
+export class ServerError extends QuickbaseError {
+    constructor(statusCode, message, options) {
+        super(message, statusCode, options);
+        this.name = 'ServerError';
+    }
+}
+/**
+ * Parse an error response from the QuickBase API
+ */
+export async function parseErrorResponse(response, requestUrl) {
+    const rayId = response.headers.get('qb-api-ray') || response.headers.get('cf-ray') || undefined;
+    let body = null;
+    try {
+        body = await response.json();
+    }
+    catch {
+        // Response body is not JSON
+    }
+    const message = body?.message || response.statusText || 'Unknown error';
+    const description = body?.description;
+    switch (response.status) {
+        case 400:
+            return new ValidationError(message, {
+                description,
+                rayId,
+                errors: body?.errors,
+            });
+        case 401:
+            return new AuthenticationError(message, { rayId });
+        case 403:
+            return new AuthorizationError(message, { rayId });
+        case 404:
+            return new NotFoundError(message, { rayId });
+        case 429: {
+            const retryAfter = response.headers.get('Retry-After');
+            const rateLimitInfo = {
+                timestamp: new Date(),
+                requestUrl,
+                httpStatus: 429,
+                retryAfter: retryAfter ? parseInt(retryAfter, 10) : undefined,
+                cfRay: response.headers.get('cf-ray') || undefined,
+                tid: response.headers.get('tid') || undefined,
+                qbApiRay: response.headers.get('qb-api-ray') || undefined,
+                attempt: 1, // Will be updated by caller
+            };
+            return new RateLimitError(rateLimitInfo, message);
+        }
+        default:
+            if (response.status >= 500) {
+                return new ServerError(response.status, message, { description, rayId });
+            }
+            return new QuickbaseError(message, response.status, { description, rayId });
+    }
+}
+/**
+ * Check if an error is retryable
+ */
+export function isRetryableError(error) {
+    if (error instanceof RateLimitError) {
+        return true;
+    }
+    if (error instanceof ServerError) {
+        return true;
+    }
+    if (error instanceof TimeoutError) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"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"}

package/dist/core/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Core module exports
+ */
+export type { QuickbaseConfig, AuthConfig, UserTokenAuthConfig, TempTokenAuthConfig, SsoTokenAuthConfig, RateLimitConfig, RetryConfig, RequestContext, RateLimitInfo, PaginationMetadata, PaginatedResponse, FieldInfo, ResolvedConfig, } from './types.js';
+export { DEFAULT_CONFIG } from './types.js';
+export { QuickbaseError, RateLimitError, AuthenticationError, AuthorizationError, NotFoundError, ValidationError, TimeoutError, ServerError, parseErrorResponse, isRetryableError, } from './errors.js';
+export { Logger, createLogger } from './logger.js';
+export { resolveConfig, getRealmHostname } from './config.js';
+export { transformDates, isIsoDateString } from './dates.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACV,eAAe,EACf,UAAU,EACV,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,SAAS,EACT,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EACL,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,9 @@
+/**
+ * Core module exports
+ */
+export { DEFAULT_CONFIG } from './types.js';
+export { QuickbaseError, RateLimitError, AuthenticationError, AuthorizationError, NotFoundError, ValidationError, TimeoutError, ServerError, parseErrorResponse, isRetryableError, } from './errors.js';
+export { Logger, createLogger } from './logger.js';
+export { resolveConfig, getRealmHostname } from './config.js';
+export { transformDates, isIsoDateString } from './dates.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAkBH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EACL,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/core/logger.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Logger utility that respects the debug configuration
+ */
+export declare class Logger {
+    private readonly enabled;
+    private readonly prefix;
+    constructor(enabled?: boolean, prefix?: string);
+    private formatMessage;
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, error?: unknown): void;
+    /**
+     * Log rate limit information
+     */
+    rateLimit(info: {
+        url: string;
+        status: number;
+        retryAfter?: number;
+        attempt: number;
+        rayId?: string;
+    }): void;
+    /**
+     * Log request timing
+     */
+    timing(method: string, url: string, durationMs: number): void;
+    /**
+     * Log retry attempt
+     */
+    retry(attempt: number, maxAttempts: number, delayMs: number, reason: string): void;
+    /**
+     * Log token operations (without exposing the actual token)
+     */
+    token(operation: 'fetch' | 'cache-hit' | 'cache-miss' | 'refresh' | 'expire', dbid?: string): void;
+}
+/**
+ * Create a no-op logger for when logging is disabled
+ * This avoids conditional checks at every log call
+ */
+export declare function createLogger(enabled: boolean): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/core/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,OAAO,GAAE,OAAe,EAAE,MAAM,GAAE,MAAuB;IAKrE,OAAO,CAAC,aAAa;IAKrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAU5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAU3C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAS3C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI;IAS7C;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,IAAI;IAUR;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAM7D;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAQlF;;OAEG;IACH,KAAK,CAAC,SAAS,EAAE,OAAO,GAAG,WAAW,GAAG,YAAY,GAAG,SAAS,GAAG,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;CAMnG;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAErD"}

package/dist/core/logger.js

@@ -0,0 +1,96 @@
+/**
+ * Logger utility that respects the debug configuration
+ */
+export class Logger {
+    enabled;
+    prefix;
+    constructor(enabled = false, prefix = 'quickbase-js') {
+        this.enabled = enabled;
+        this.prefix = prefix;
+    }
+    formatMessage(level, message) {
+        const timestamp = new Date().toISOString();
+        return `[${timestamp}] [${this.prefix}] [${level}] ${message}`;
+    }
+    debug(message, data) {
+        if (this.enabled) {
+            if (data !== undefined) {
+                console.log(this.formatMessage('DEBUG', message), data);
+            }
+            else {
+                console.log(this.formatMessage('DEBUG', message));
+            }
+        }
+    }
+    info(message, data) {
+        if (this.enabled) {
+            if (data !== undefined) {
+                console.info(this.formatMessage('INFO', message), data);
+            }
+            else {
+                console.info(this.formatMessage('INFO', message));
+            }
+        }
+    }
+    warn(message, data) {
+        // Warnings are always logged, regardless of debug setting
+        if (data !== undefined) {
+            console.warn(this.formatMessage('WARN', message), data);
+        }
+        else {
+            console.warn(this.formatMessage('WARN', message));
+        }
+    }
+    error(message, error) {
+        // Errors are always logged, regardless of debug setting
+        if (error !== undefined) {
+            console.error(this.formatMessage('ERROR', message), error);
+        }
+        else {
+            console.error(this.formatMessage('ERROR', message));
+        }
+    }
+    /**
+     * Log rate limit information
+     */
+    rateLimit(info) {
+        if (this.enabled) {
+            this.debug(`Rate limited (attempt ${info.attempt}): ${info.url} - ` +
+                `Status ${info.status}, Retry-After: ${info.retryAfter ?? 'not specified'}s` +
+                (info.rayId ? `, Ray: ${info.rayId}` : ''));
+        }
+    }
+    /**
+     * Log request timing
+     */
+    timing(method, url, durationMs) {
+        if (this.enabled) {
+            this.debug(`${method} ${url} completed in ${durationMs}ms`);
+        }
+    }
+    /**
+     * Log retry attempt
+     */
+    retry(attempt, maxAttempts, delayMs, reason) {
+        if (this.enabled) {
+            this.debug(`Retry ${attempt}/${maxAttempts} in ${delayMs}ms: ${reason}`);
+        }
+    }
+    /**
+     * Log token operations (without exposing the actual token)
+     */
+    token(operation, dbid) {
+        if (this.enabled) {
+            const target = dbid ? ` for dbid: ${dbid}` : '';
+            this.debug(`Token ${operation}${target}`);
+        }
+    }
+}
+/**
+ * Create a no-op logger for when logging is disabled
+ * This avoids conditional checks at every log call
+ */
+export function createLogger(enabled) {
+    return new Logger(enabled);
+}
+//# sourceMappingURL=logger.js.map

package/dist/core/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"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"}

package/dist/core/types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Core types for the QuickBase SDK v2
+ */
+export interface QuickbaseConfig {
+    /** Your QuickBase realm (e.g., "mycompany" for mycompany.quickbase.com) */
+    realm: string;
+    /** Authentication configuration */
+    auth: AuthConfig;
+    /** Rate limiting and retry configuration */
+    rateLimit?: RateLimitConfig;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Custom fetch implementation (default: global fetch) */
+    fetchApi?: typeof fetch;
+    /** Base URL override (default: https://api.quickbase.com/v1) */
+    baseUrl?: string;
+    /** Automatically paginate all paginated requests when awaited (default: false) */
+    autoPaginate?: boolean;
+    /** Convert ISO date strings in responses to JavaScript Date objects (default: true) */
+    convertDates?: boolean;
+}
+export type AuthConfig = UserTokenAuthConfig | TempTokenAuthConfig | SsoTokenAuthConfig;
+export interface UserTokenAuthConfig {
+    type: 'user-token';
+    /** Your QuickBase user token */
+    userToken: string;
+}
+export interface TempTokenAuthConfig {
+    type: 'temp-token';
+    /**
+     * User token used to fetch temporary tokens (optional)
+     * Not required when running in QuickBase Code Pages - the browser session is used
+     */
+    userToken?: string;
+    /** App token (optional, for apps that require it) */
+    appToken?: string;
+    /** Token lifespan in milliseconds (default: 290000 = ~4m50s) */
+    tokenLifespanMs?: number;
+}
+export interface SsoTokenAuthConfig {
+    type: 'sso';
+    /** SAML token for SSO authentication */
+    samlToken: string;
+}
+export interface RateLimitConfig {
+    /**
+     * Client-side proactive throttling (optional)
+     * QuickBase allows 100 requests per 10 seconds per user token
+     */
+    proactiveThrottle?: {
+        enabled: boolean;
+        /** Requests allowed per 10 seconds (default: 100) */
+        requestsPer10Seconds?: number;
+    };
+    /** Retry configuration for rate limit and server errors */
+    retry?: RetryConfig;
+    /** Callback when rate limited */
+    onRateLimit?: (info: RateLimitInfo) => void;
+}
+export interface RetryConfig {
+    /** Maximum retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Initial delay in milliseconds (default: 1000) */
+    initialDelayMs?: number;
+    /** Maximum delay in milliseconds (default: 30000) */
+    maxDelayMs?: number;
+    /** Backoff multiplier (default: 2) */
+    multiplier?: number;
+}
+export interface RequestContext {
+    /** The API method being called */
+    methodName: string;
+    /** Current attempt number (1-based) */
+    attempt: number;
+    /** Maximum attempts allowed */
+    maxAttempts: number;
+    /** Database ID (for temp token auth) */
+    dbid?: string;
+    /** Request start timestamp */
+    startTime: number;
+}
+export interface RateLimitInfo {
+    /** When the rate limit occurred */
+    timestamp: Date;
+    /** The request URL */
+    requestUrl: string;
+    /** HTTP status code */
+    httpStatus: number;
+    /** Retry-After header value (seconds) */
+    retryAfter?: number;
+    /** Cloudflare ray ID */
+    cfRay?: string;
+    /** Transaction ID */
+    tid?: string;
+    /** QuickBase API ray ID */
+    qbApiRay?: string;
+    /** Which retry attempt this was */
+    attempt: number;
+}
+export interface PaginationMetadata {
+    totalRecords: number;
+    numRecords: number;
+    numFields: number;
+    skip?: number;
+    top?: number;
+}
+export interface PaginatedResponse<T> {
+    data: T[];
+    metadata: PaginationMetadata;
+    fields?: FieldInfo[];
+}
+export interface FieldInfo {
+    id: number;
+    label: string;
+    type: string;
+}
+export interface ResolvedConfig {
+    realm: string;
+    baseUrl: string;
+    timeout: number;
+    debug: boolean;
+    fetchApi: typeof fetch;
+    auth: AuthConfig;
+    retry: Required<RetryConfig>;
+    proactiveThrottle: {
+        enabled: boolean;
+        requestsPer10Seconds: number;
+    };
+    onRateLimit?: (info: RateLimitInfo) => void;
+    autoPaginate: boolean;
+    convertDates: boolean;
+}
+/** Default configuration values */
+export declare const DEFAULT_CONFIG: {
+    readonly baseUrl: "https://api.quickbase.com/v1";
+    readonly timeout: 30000;
+    readonly debug: false;
+    readonly retry: {
+        readonly maxAttempts: 3;
+        readonly initialDelayMs: 1000;
+        readonly maxDelayMs: 30000;
+        readonly multiplier: 2;
+    };
+    readonly proactiveThrottle: {
+        readonly enabled: false;
+        readonly requestsPer10Seconds: 100;
+    };
+    readonly tempTokenLifespanMs: 290000;
+    readonly autoPaginate: false;
+    readonly convertDates: true;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/core/types.js

@@ -0,0 +1,23 @@
+/**
+ * Core types for the QuickBase SDK v2
+ */
+/** Default configuration values */
+export const DEFAULT_CONFIG = {
+    baseUrl: 'https://api.quickbase.com/v1',
+    timeout: 30000,
+    debug: false,
+    retry: {
+        maxAttempts: 3,
+        initialDelayMs: 1000,
+        maxDelayMs: 30000,
+        multiplier: 2,
+    },
+    proactiveThrottle: {
+        enabled: false,
+        requestsPer10Seconds: 100,
+    },
+    tempTokenLifespanMs: 290000, // ~4m50s (QuickBase tokens expire at 5m)
+    autoPaginate: false,
+    convertDates: true,
+};
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AA+KH,mCAAmC;AACnC,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,OAAO,EAAE,8BAA8B;IACvC,OAAO,EAAE,KAAK;IACd,KAAK,EAAE,KAAK;IACZ,KAAK,EAAE;QACL,WAAW,EAAE,CAAC;QACd,cAAc,EAAE,IAAI;QACpB,UAAU,EAAE,KAAK;QACjB,UAAU,EAAE,CAAC;KACd;IACD,iBAAiB,EAAE;QACjB,OAAO,EAAE,KAAK;QACd,oBAAoB,EAAE,GAAG;KAC1B;IACD,mBAAmB,EAAE,MAAM,EAAE,yCAAyC;IACtE,YAAY,EAAE,KAAK;IACnB,YAAY,EAAE,IAAI;CACV,CAAC"}

package/dist/generated/client.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Auto-generated QuickBase API client implementation
+ * DO NOT EDIT - Regenerate with: npm run spec:generate
+ */
+import type { QuickbaseAPI } from './types.js';
+export type RequestFn = <T>(options: {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+}) => Promise<T>;
+/**
+ * Create typed API methods from a request function
+ * @param request - The request executor function
+ * @param autoPaginate - Default auto-pagination behavior (default: false)
+ */
+export declare function createApiMethods(request: RequestFn, autoPaginate?: boolean): QuickbaseAPI;
+//# sourceMappingURL=client.d.ts.map

package/dist/generated/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/generated/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EACV,YAAY,EA6Ib,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE;IACnC,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;CAC/D,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAEjB;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,EAAE,YAAY,GAAE,OAAe,GAAG,YAAY,CA45ChG"}