@deliverart/sdk-js-core 2.5.34 → 2.6.0

package/dist/index.d.cts

@@ -5,11 +5,21 @@ interface ApiClientPlugin<T extends ApiExtension = Record<string, unknown>> {
     setup: (client: ApiClient<Record<string, unknown>>) => T;
 }
 
+type UnpaginatedResponse<T> = T extends {
+    data: infer U;
+} ? U : T;
 declare abstract class AbstractApiRequest<TInputSchema extends ZodType<any, any, any>, TOutputSchema extends ZodType<any, any, any>, Query = unknown, Headers = unknown> {
     readonly input: input<TInputSchema>;
     readonly options?: {
         query?: Query;
         headers?: Headers;
+        /**
+         * Toggle pagination at call-time if the request supports it.
+         * - true: attach pagination (if `getPagination` returns a value)
+         * - false: return a plain array of items
+         * - undefined: fall back to `paginationDefaultEnabled` (true if not set)
+         */
+        pagination?: boolean;
     } | undefined;
     abstract readonly method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
     abstract readonly contentType: 'application/json' | 'multipart/form-data' | 'application/merge-patch+json';
@@ -18,16 +28,39 @@ declare abstract class AbstractApiRequest<TInputSchema extends ZodType<any, any,
     abstract readonly outputSchema: TOutputSchema;
     abstract readonly querySchema?: ZodType<Query>;
     abstract readonly headersSchema?: ZodType<Headers>;
+    /**
+     * Optional hints to enable automatic list parsing.
+     * - If `listItemSchema` is provided, `parseResponse` will automatically
+     *   parse arrays and optionally attach pagination when enabled.
+     * - Pagination attachment requires overriding `getPagination` in concrete requests
+     *   to compute pagination metadata from the raw response (e.g. headers).
+     */
+    readonly listItemSchema?: ZodType<any, any, any>;
+    /** Whether pagination is enabled by default for this request (if available). */
+    readonly paginationDefaultEnabled?: boolean;
     protected constructor(input: input<TInputSchema>, options?: {
         query?: Query;
         headers?: Headers;
+        /**
+         * Toggle pagination at call-time if the request supports it.
+         * - true: attach pagination (if `getPagination` returns a value)
+         * - false: return a plain array of items
+         * - undefined: fall back to `paginationDefaultEnabled` (true if not set)
+         */
+        pagination?: boolean;
     } | undefined);
     abstract getPath(): string;
+    /**
+     * Override this in list requests to provide pagination metadata from the raw HTTP response.
+     * Default implementation uses `responseToPagination`.
+     * Return `undefined` if pagination cannot be resolved.
+     */
+    protected getPagination(rawResponse: Response): unknown | undefined;
     validateInput(): output<TInputSchema>;
     validateQuery(): Query | undefined;
     validateHeaders(): Headers | undefined;
     validateOutput(data: unknown): output<TOutputSchema>;
-    parseResponse(data: unknown, rawResponse?: Response): output<TOutputSchema>;
+    parseResponse(data: unknown, rawResponse?: Response, paginationOption?: boolean): output<TOutputSchema>;
 }
 type RequestContext = {
     url: URL;
@@ -41,7 +74,14 @@ type ParsedResponse = {
 type ResponseMiddleware = (parsed: ParsedResponse, requestCtx: RequestContext) => Promise<ParsedResponse> | ParsedResponse;
 interface ApiClientBase {
     fetch: typeof fetch;
-    call<TInputSchema extends ZodType<any, any, any>, TOutputSchema extends ZodType<any, any, any>, Q = unknown, H = unknown>(request: AbstractApiRequest<TInputSchema, TOutputSchema, Q, H>): Promise<output<TOutputSchema>>;
+    call<TInputSchema extends ZodType<any, any, any>, TOutputSchema extends ZodType<any, any, any>, Q = unknown, H = unknown>(request: AbstractApiRequest<TInputSchema, TOutputSchema, Q, H>, options: {
+        pagination: false;
+        itemsPerPage?: number;
+    }): Promise<UnpaginatedResponse<output<TOutputSchema>>>;
+    call<TInputSchema extends ZodType<any, any, any>, TOutputSchema extends ZodType<any, any, any>, Q = unknown, H = unknown>(request: AbstractApiRequest<TInputSchema, TOutputSchema, Q, H>, options?: {
+        pagination?: true;
+        itemsPerPage?: number;
+    }): Promise<output<TOutputSchema>>;
     addPlugin: <T extends ApiExtension>(plugin: ApiClientPlugin<T>) => ApiClient<T>;
     addRequestMiddleware: (middleware: RequestMiddleware) => void;
     addResponseMiddleware: (middleware: ResponseMiddleware) => void;
@@ -61,4 +101,4 @@ declare class OutputValidationError extends Error {
     constructor(issues: ZodIssue[]);
 }
 
-export { AbstractApiRequest, type ApiClient, type ApiClientPlugin, type ApiExtension, InputValidationError, OutputValidationError, createApiClient };
+export { AbstractApiRequest, type ApiClient, type ApiClientPlugin, type ApiExtension, InputValidationError, OutputValidationError, type UnpaginatedResponse, createApiClient };

package/dist/index.d.ts

@@ -5,11 +5,21 @@ interface ApiClientPlugin<T extends ApiExtension = Record<string, unknown>> {
     setup: (client: ApiClient<Record<string, unknown>>) => T;
 }
 
+type UnpaginatedResponse<T> = T extends {
+    data: infer U;
+} ? U : T;
 declare abstract class AbstractApiRequest<TInputSchema extends ZodType<any, any, any>, TOutputSchema extends ZodType<any, any, any>, Query = unknown, Headers = unknown> {
     readonly input: input<TInputSchema>;
     readonly options?: {
         query?: Query;
         headers?: Headers;
+        /**
+         * Toggle pagination at call-time if the request supports it.
+         * - true: attach pagination (if `getPagination` returns a value)
+         * - false: return a plain array of items
+         * - undefined: fall back to `paginationDefaultEnabled` (true if not set)
+         */
+        pagination?: boolean;
     } | undefined;
     abstract readonly method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
     abstract readonly contentType: 'application/json' | 'multipart/form-data' | 'application/merge-patch+json';
@@ -18,16 +28,39 @@ declare abstract class AbstractApiRequest<TInputSchema extends ZodType<any, any,
     abstract readonly outputSchema: TOutputSchema;
     abstract readonly querySchema?: ZodType<Query>;
     abstract readonly headersSchema?: ZodType<Headers>;
+    /**
+     * Optional hints to enable automatic list parsing.
+     * - If `listItemSchema` is provided, `parseResponse` will automatically
+     *   parse arrays and optionally attach pagination when enabled.
+     * - Pagination attachment requires overriding `getPagination` in concrete requests
+     *   to compute pagination metadata from the raw response (e.g. headers).
+     */
+    readonly listItemSchema?: ZodType<any, any, any>;
+    /** Whether pagination is enabled by default for this request (if available). */
+    readonly paginationDefaultEnabled?: boolean;
     protected constructor(input: input<TInputSchema>, options?: {
         query?: Query;
         headers?: Headers;
+        /**
+         * Toggle pagination at call-time if the request supports it.
+         * - true: attach pagination (if `getPagination` returns a value)
+         * - false: return a plain array of items
+         * - undefined: fall back to `paginationDefaultEnabled` (true if not set)
+         */
+        pagination?: boolean;
     } | undefined);
     abstract getPath(): string;
+    /**
+     * Override this in list requests to provide pagination metadata from the raw HTTP response.
+     * Default implementation uses `responseToPagination`.
+     * Return `undefined` if pagination cannot be resolved.
+     */
+    protected getPagination(rawResponse: Response): unknown | undefined;
     validateInput(): output<TInputSchema>;
     validateQuery(): Query | undefined;
     validateHeaders(): Headers | undefined;
     validateOutput(data: unknown): output<TOutputSchema>;
-    parseResponse(data: unknown, rawResponse?: Response): output<TOutputSchema>;
+    parseResponse(data: unknown, rawResponse?: Response, paginationOption?: boolean): output<TOutputSchema>;
 }
 type RequestContext = {
     url: URL;
@@ -41,7 +74,14 @@ type ParsedResponse = {
 type ResponseMiddleware = (parsed: ParsedResponse, requestCtx: RequestContext) => Promise<ParsedResponse> | ParsedResponse;
 interface ApiClientBase {
     fetch: typeof fetch;
-    call<TInputSchema extends ZodType<any, any, any>, TOutputSchema extends ZodType<any, any, any>, Q = unknown, H = unknown>(request: AbstractApiRequest<TInputSchema, TOutputSchema, Q, H>): Promise<output<TOutputSchema>>;
+    call<TInputSchema extends ZodType<any, any, any>, TOutputSchema extends ZodType<any, any, any>, Q = unknown, H = unknown>(request: AbstractApiRequest<TInputSchema, TOutputSchema, Q, H>, options: {
+        pagination: false;
+        itemsPerPage?: number;
+    }): Promise<UnpaginatedResponse<output<TOutputSchema>>>;
+    call<TInputSchema extends ZodType<any, any, any>, TOutputSchema extends ZodType<any, any, any>, Q = unknown, H = unknown>(request: AbstractApiRequest<TInputSchema, TOutputSchema, Q, H>, options?: {
+        pagination?: true;
+        itemsPerPage?: number;
+    }): Promise<output<TOutputSchema>>;
     addPlugin: <T extends ApiExtension>(plugin: ApiClientPlugin<T>) => ApiClient<T>;
     addRequestMiddleware: (middleware: RequestMiddleware) => void;
     addResponseMiddleware: (middleware: ResponseMiddleware) => void;
@@ -61,4 +101,4 @@ declare class OutputValidationError extends Error {
     constructor(issues: ZodIssue[]);
 }
 
-export { AbstractApiRequest, type ApiClient, type ApiClientPlugin, type ApiExtension, InputValidationError, OutputValidationError, createApiClient };
+export { AbstractApiRequest, type ApiClient, type ApiClientPlugin, type ApiExtension, InputValidationError, OutputValidationError, type UnpaginatedResponse, createApiClient };