@deliverart/sdk-js-core 0.0.0-dev-20260721002647

package/dist/index.d.cts

@@ -0,0 +1,125 @@
+import { ZodType, input, output, ZodError, z } from 'zod';
+import { IriObject } from '@deliverart/sdk-js-global-types';
+
+type ApiExtension = Record<string, unknown>;
+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' | 'PUT' | 'PATCH' | 'DELETE';
+    abstract readonly contentType: 'application/json' | 'multipart/form-data' | 'application/merge-patch+json';
+    abstract readonly accept: 'application/json';
+    abstract readonly inputSchema: TInputSchema;
+    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, useArraySchema?: boolean): output<TOutputSchema>;
+    parseResponse(data: unknown, rawResponse?: Response, paginationOption?: boolean): output<TOutputSchema>;
+}
+type RequestContext = {
+    url: URL;
+    init: RequestInit;
+};
+type RequestMiddleware = (ctx: RequestContext) => Promise<RequestContext> | RequestContext;
+type ParsedResponse = {
+    response: Response;
+    body: unknown;
+};
+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>, 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;
+}
+type ApiClient<Extensions extends ApiExtension = NonNullable<unknown>> = ApiClientBase & Extensions;
+declare function createApiClient<Extensions extends ApiExtension = NonNullable<unknown>>(config: {
+    baseUrl: string;
+}): ApiClient<Extensions>;
+
+type ZodIssue = ZodError['issues'][number];
+declare class InputValidationError extends Error {
+    readonly issues: ZodIssue[];
+    constructor(issues: ZodIssue[]);
+}
+declare class OutputValidationError extends Error {
+    readonly issues: ZodIssue[];
+    constructor(issues: ZodIssue[]);
+}
+
+declare const serializedIriObjectSchema: z.ZodObject<{
+    iri: z.ZodString;
+    params: z.ZodRecord<z.ZodString, z.ZodString>;
+    __pattern: z.ZodString;
+}, z.core.$strict>;
+type SerializedIriObject<TPattern extends string = string> = {
+    iri: string;
+    params: Record<string, string>;
+    __pattern: TPattern;
+};
+type DeepDeserialized<T> = T extends SerializedIriObject<infer P> ? IriObject<P> : T extends Array<infer U> ? DeepDeserialized<U>[] : T extends object ? {
+    [K in keyof T]: DeepDeserialized<T[K]>;
+} : T;
+type DeepSerialized<T> = T extends IriObject<infer P> ? SerializedIriObject<P> : T extends Array<infer U> ? DeepSerialized<U>[] : T extends object ? {
+    [K in keyof T]: DeepSerialized<T[K]>;
+} : T;
+declare function serializeForClient<T>(input: T): DeepSerialized<T>;
+declare function deserializeFromClient<T extends SerializedIriObject<P>, P extends string>(input: T): IriObject<P>;
+declare function deserializeFromClient<T>(input: T): DeepDeserialized<T>;
+
+export { AbstractApiRequest, type ApiClient, type ApiClientPlugin, type ApiExtension, type DeepDeserialized, type DeepSerialized, InputValidationError, OutputValidationError, type SerializedIriObject, type UnpaginatedResponse, createApiClient, deserializeFromClient, serializeForClient, serializedIriObjectSchema };

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+import { ZodType, input, output, ZodError, z } from 'zod';
+import { IriObject } from '@deliverart/sdk-js-global-types';
+
+type ApiExtension = Record<string, unknown>;
+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' | 'PUT' | 'PATCH' | 'DELETE';
+    abstract readonly contentType: 'application/json' | 'multipart/form-data' | 'application/merge-patch+json';
+    abstract readonly accept: 'application/json';
+    abstract readonly inputSchema: TInputSchema;
+    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, useArraySchema?: boolean): output<TOutputSchema>;
+    parseResponse(data: unknown, rawResponse?: Response, paginationOption?: boolean): output<TOutputSchema>;
+}
+type RequestContext = {
+    url: URL;
+    init: RequestInit;
+};
+type RequestMiddleware = (ctx: RequestContext) => Promise<RequestContext> | RequestContext;
+type ParsedResponse = {
+    response: Response;
+    body: unknown;
+};
+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>, 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;
+}
+type ApiClient<Extensions extends ApiExtension = NonNullable<unknown>> = ApiClientBase & Extensions;
+declare function createApiClient<Extensions extends ApiExtension = NonNullable<unknown>>(config: {
+    baseUrl: string;
+}): ApiClient<Extensions>;
+
+type ZodIssue = ZodError['issues'][number];
+declare class InputValidationError extends Error {
+    readonly issues: ZodIssue[];
+    constructor(issues: ZodIssue[]);
+}
+declare class OutputValidationError extends Error {
+    readonly issues: ZodIssue[];
+    constructor(issues: ZodIssue[]);
+}
+
+declare const serializedIriObjectSchema: z.ZodObject<{
+    iri: z.ZodString;
+    params: z.ZodRecord<z.ZodString, z.ZodString>;
+    __pattern: z.ZodString;
+}, z.core.$strict>;
+type SerializedIriObject<TPattern extends string = string> = {
+    iri: string;
+    params: Record<string, string>;
+    __pattern: TPattern;
+};
+type DeepDeserialized<T> = T extends SerializedIriObject<infer P> ? IriObject<P> : T extends Array<infer U> ? DeepDeserialized<U>[] : T extends object ? {
+    [K in keyof T]: DeepDeserialized<T[K]>;
+} : T;
+type DeepSerialized<T> = T extends IriObject<infer P> ? SerializedIriObject<P> : T extends Array<infer U> ? DeepSerialized<U>[] : T extends object ? {
+    [K in keyof T]: DeepSerialized<T[K]>;
+} : T;
+declare function serializeForClient<T>(input: T): DeepSerialized<T>;
+declare function deserializeFromClient<T extends SerializedIriObject<P>, P extends string>(input: T): IriObject<P>;
+declare function deserializeFromClient<T>(input: T): DeepDeserialized<T>;
+
+export { AbstractApiRequest, type ApiClient, type ApiClientPlugin, type ApiExtension, type DeepDeserialized, type DeepSerialized, InputValidationError, OutputValidationError, type SerializedIriObject, type UnpaginatedResponse, createApiClient, deserializeFromClient, serializeForClient, serializedIriObjectSchema };