@kontent-ai/core-sdk 12.0.0-preview.4 → 12.0.0-preview.40

package/dist/sdk/resolve-query.js

@@ -0,0 +1,172 @@
+import { getDefaultHttpService } from "../http/http.service.js";
+import { createSdkError } from "../utils/error.utils.js";
+import { createAuthorizationHeader, createContinuationHeader, createSdkIdHeader, extractContinuationToken } from "../utils/header.utils.js";
+import { resolveSchema } from "../utils/schema.utils.js";
+import { tryCatch } from "../utils/try-catch.utils.js";
+import { parseResponse } from "./sdk-utils.js";
+export function inspectQuery(data) {
+    const { success, data: resolvedUrl, error } = resolveUrl({ url: data.url, baseUrl: data.config.baseUrl, mapError: data.mapError });
+    if (!success) {
+        return { success: false, error };
+    }
+    return {
+        success: true,
+        data: {
+            url: resolvedUrl,
+            requestHeaders: getCombinedRequestHeaders({
+                requestHeaders: data.requestHeaders ?? [],
+                continuationToken: data.continuationToken,
+                authorizationApiKey: data.authorizationApiKey,
+                sdkInfo: data.sdkInfo,
+            }),
+            body: data.body,
+            method: data.method,
+        },
+    };
+}
+export async function resolveQuery(data) {
+    const { success, data: resolvedQueryData, error } = prepareQueryData(data);
+    if (!success) {
+        return { success: false, error };
+    }
+    return await executeQuery(resolvedQueryData);
+}
+function prepareQueryData(data) {
+    const { success: inspectionSuccess, data: inspectionData, error: inspectionError } = inspectQuery(data);
+    if (!inspectionSuccess) {
+        return { success: false, error: inspectionError };
+    }
+    return {
+        success: true,
+        data: {
+            requestHeaders: inspectionData.requestHeaders,
+            url: inspectionData.url,
+            httpService: getHttpService(data.config),
+            body: data.body,
+            method: data.method,
+            abortSignal: data.abortSignal,
+            schema: data.schema,
+            responseValidation: data.config.runtimeValidation,
+            mapError: data.mapError,
+            mapMetadata: data.mapMetadata,
+            mapExtraResponseProps: data.mapExtraResponseProps,
+        },
+    };
+}
+async function executeQuery({ url, requestHeaders, httpService, body, method, abortSignal, schema, responseValidation, mapError, mapMetadata, mapExtraResponseProps, }) {
+    const { success, response, error } = await httpService.request({
+        body,
+        url,
+        method,
+        abortSignal,
+        requestHeaders,
+    });
+    if (!success) {
+        return { success: false, error: mapError(error) };
+    }
+    if (responseValidation?.validateResponses) {
+        const resolvedSchema = await resolveSchema(schema);
+        if (resolvedSchema) {
+            const validationError = await parseResponse({
+                url: response.adapterResponse.url,
+                payload: response.payload,
+                schema: resolvedSchema,
+            });
+            if (validationError) {
+                return { success: false, error: mapError(validationError.error) };
+            }
+        }
+    }
+    const continuationTokenFromResponse = extractContinuationToken(response.adapterResponse.responseHeaders);
+    return {
+        success: true,
+        response: {
+            ...mapExtraResponseProps(response),
+            payload: response.payload,
+            meta: {
+                ...mapMetadata(response, { continuationToken: continuationTokenFromResponse }),
+                url: response.adapterResponse.url,
+                responseHeaders: response.adapterResponse.responseHeaders,
+                status: response.adapterResponse.status,
+                continuationToken: continuationTokenFromResponse,
+            },
+        },
+    };
+}
+export function resolveUrl({ url, baseUrl, mapError, }) {
+    const returnWithBaseUrl = (parsedUrl) => {
+        if (!baseUrl) {
+            return {
+                success: true,
+                data: parsedUrl,
+            };
+        }
+        const { success, data: parsedUrlWithBaseUrl, error } = setBaseUrl(parsedUrl, baseUrl);
+        if (!success) {
+            return {
+                success: false,
+                error: mapError(error),
+            };
+        }
+        return {
+            success: true,
+            data: parsedUrlWithBaseUrl,
+        };
+    };
+    if (typeof url === "string") {
+        const { success, data: parsedUrl, error } = tryCatch(() => new URL(url));
+        if (!success) {
+            return {
+                success: false,
+                error: mapError(createInvalidUrlError(url, error)),
+            };
+        }
+        return returnWithBaseUrl(parsedUrl);
+    }
+    return returnWithBaseUrl(url);
+}
+function createInvalidUrlError(invalidUrl, error) {
+    return createSdkError({
+        baseErrorData: {
+            message: `Failed to parse url '${invalidUrl}'`,
+            url: invalidUrl,
+            retryStrategyOptions: undefined,
+            retryAttempt: undefined,
+        },
+        details: {
+            reason: "invalidUrl",
+            originalError: error,
+        },
+    });
+}
+function setBaseUrl(url, baseUrl) {
+    const clonedUrl = new URL(url.toString());
+    const baseUrlString = `${baseUrl.protocol}://${baseUrl.host}`;
+    // Direct host assignment is a silent no-op for invalid values per the URL spec,
+    // so validate by constructing a full URL first.
+    const { success, data: parsedBaseUrl, error } = tryCatch(() => new URL(baseUrlString));
+    if (!success) {
+        return {
+            success: false,
+            error: createInvalidUrlError(baseUrlString, error),
+        };
+    }
+    clonedUrl.protocol = parsedBaseUrl.protocol;
+    clonedUrl.host = parsedBaseUrl.host;
+    return {
+        success: true,
+        data: clonedUrl,
+    };
+}
+function getHttpService(config) {
+    return config.httpService ?? getDefaultHttpService();
+}
+function getCombinedRequestHeaders({ requestHeaders, continuationToken, authorizationApiKey, sdkInfo, }) {
+    return [
+        createSdkIdHeader(sdkInfo),
+        ...requestHeaders.filter((header) => header.name !== "X-KC-SDKID"),
+        ...(continuationToken ? [createContinuationHeader(continuationToken)] : []),
+        ...(authorizationApiKey ? [createAuthorizationHeader(authorizationApiKey)] : []),
+    ];
+}
+//# sourceMappingURL=resolve-query.js.map

package/dist/sdk/resolve-query.js.map

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

package/dist/sdk/sdk-config.d.ts

@@ -0,0 +1,24 @@
+import * as z from "zod/mini";
+export declare const nilUuid = "00000000-0000-0000-0000-000000000000";
+export declare const kontentUuidSchema: z.ZodMiniUnion<readonly [z.ZodMiniUUID, z.ZodMiniLiteral<"00000000-0000-0000-0000-000000000000">]>;
+export declare const strictCodenameSchema: z.ZodMiniString<string>;
+/**
+ * Builds a Zod schema for a codename field.
+ *
+ * The generic type parameter `TCodenames` is a **TypeScript-only hint** - it
+ * narrows the schema's output type for consumers (e.g.
+ * `codenameOf<"article" | "product">()` returns `z.ZodMiniType<"article" | "product">`
+ * for autocomplete and downstream type inference) but is not enforced at runtime.
+ *
+ * At runtime the schema only checks that the value is a string. Two reasons:
+ *
+ * 1. Codenames are not a closed set - editors can add a new content type,
+ *    taxonomy term, language, etc. at any time. A `z.literal(codenames)` schema
+ *    would reject newly-added codenames once they appear in API responses, even
+ *    though those values are perfectly valid.
+ * 2. Format-checking every codename on every response is unnecessary cost - the
+ *    Kontent.ai API contract guarantees the format, so the SDK trusts it.
+ *
+ * If you need strict format validation (e.g. for inputs in Management SDK), use `strictCodenameSchema` schema instead.
+ */
+export declare function codenameOf<TCodenames extends string = string>(): z.ZodMiniType<TCodenames>;

package/dist/sdk/sdk-config.js

@@ -0,0 +1,31 @@
+import * as z from "zod/mini";
+export const nilUuid = "00000000-0000-0000-0000-000000000000";
+export const kontentUuidSchema = z.union([z.uuid({ version: "v4" }), z.literal(nilUuid)]);
+export const strictCodenameSchema = z.string().check(z.regex(/^[a-z][a-z0-9_]*$/, {
+    error: "Codename must start with a lowercase letter and contain only lowercase letters, digits, and underscores",
+}));
+/**
+ * Builds a Zod schema for a codename field.
+ *
+ * The generic type parameter `TCodenames` is a **TypeScript-only hint** - it
+ * narrows the schema's output type for consumers (e.g.
+ * `codenameOf<"article" | "product">()` returns `z.ZodMiniType<"article" | "product">`
+ * for autocomplete and downstream type inference) but is not enforced at runtime.
+ *
+ * At runtime the schema only checks that the value is a string. Two reasons:
+ *
+ * 1. Codenames are not a closed set - editors can add a new content type,
+ *    taxonomy term, language, etc. at any time. A `z.literal(codenames)` schema
+ *    would reject newly-added codenames once they appear in API responses, even
+ *    though those values are perfectly valid.
+ * 2. Format-checking every codename on every response is unnecessary cost - the
+ *    Kontent.ai API contract guarantees the format, so the SDK trusts it.
+ *
+ * If you need strict format validation (e.g. for inputs in Management SDK), use `strictCodenameSchema` schema instead.
+ */
+export function codenameOf() {
+    return z.custom((value) => typeof value === "string", {
+        error: "Invalid codename",
+    });
+}
+//# sourceMappingURL=sdk-config.js.map

package/dist/sdk/sdk-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-config.js","sourceRoot":"","sources":["../../lib/sdk/sdk-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAE9B,MAAM,CAAC,MAAM,OAAO,GAAG,sCAAsC,CAAC;AAE9D,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAE1F,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CACnD,CAAC,CAAC,KAAK,CAAC,mBAAmB,EAAE;IAC5B,KAAK,EAAE,yGAAyG;CAChH,CAAC,CACF,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,UAAU;IACzB,OAAO,CAAC,CAAC,MAAM,CAAa,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,EAAE;QACjE,KAAK,EAAE,kBAAkB;KACzB,CAAC,CAAC;AACJ,CAAC"}

package/dist/sdk/sdk-models.d.ts

@@ -2,18 +2,23 @@
  * Shared query models/types intended to be reused across SDKs (e.g. Sync, Delivery, Management)
  * to keep common code and behavior consistent.
  */
-import type { AdapterResponse, HttpResponse, HttpService } from "../http/http.models.js";
-import type { CoreSdkError } from "../models/error.models.js";
+import type { AdapterPayload, AdapterResponse, HttpRequestBody, HttpResponse, HttpService, PagingConfig } from "../http/http.models.js";
+import type { Header, HttpMethod, SdkInfo } from "../models/core.models.js";
+import type { KontentSdkError } from "../models/error.models.js";
 import type { JsonValue } from "../models/json.models.js";
-import type { Prettify } from "../models/utility.models.js";
-export type SdkResponseMeta<TExtraMetadata = unknown> = Pick<AdapterResponse, "status" | "responseHeaders"> & {
-    readonly continuationToken?: string;
-} & TExtraMetadata;
-export type SdkResponse<TPayload, TExtraMetadata = unknown> = {
+import type { PickStringLiteral } from "../models/utility.types.js";
+import type { SchemaInput } from "../utils/schema.utils.js";
+import type { Failure, Success, TryCatchResult } from "../utils/try-catch.utils.js";
+export type QueryResponseMeta<TMeta> = Pick<AdapterResponse<AdapterPayload>, "status" | "responseHeaders" | "url"> & TMeta;
+export type QueryResponse<TPayload extends JsonValue, TMeta = unknown, TExtra = unknown> = {
     readonly payload: TPayload;
-    readonly meta: SdkResponseMeta<TExtraMetadata>;
+    readonly meta: QueryResponseMeta<TMeta>;
+} & TExtra;
+export type BaseUrl = {
+    readonly protocol: "https" | "http";
+    readonly host: string;
 };
-export type SdkConfig = {
+export type SdkConfig<TExtendedConfig = unknown> = {
     /**
      * The HTTP service to use for the request. If not provided, the default HTTP service will be used.
      *
@@ -27,56 +32,129 @@ export type SdkConfig = {
      *
      * If provided, it will override the default base URL based on selected API mode.
      */
-    readonly baseUrl?: string;
+    readonly baseUrl?: BaseUrl;
     /**
-     * Configuration for response validation.
+     * Configuration for runtime validation against expected schema.
      */
-    readonly responseValidation?: {
+    readonly runtimeValidation?: {
         /**
-         * When enabled, the response payload will be validated against the expected Zod schema from which the types
+         * When enabled, the response data will be validated against the expected Zod schema from which the types
          * this library are based on. This ensures that you are working with the correct data types.
          *
          * @default false
          */
-        readonly enable: boolean;
+        readonly validateResponses: boolean;
     };
+} & TExtendedConfig;
+export type Query<TError = KontentSdkError> = {
+    readonly inspect: () => TryCatchResult<QueryInspection, TError>;
 };
-export type Query<TPayload, TExtraData = unknown> = {
-    toUrl(): string;
-    toPromise(): Promise<QueryResult<SdkResponse<TPayload, TExtraData>>>;
+export type FetchQuery<TPayload extends JsonValue, TError = KontentSdkError, TMeta = unknown, TExtra = unknown> = Query<TError> & {
+    fetchSafe(): Promise<SafeQueryResult<QueryResponse<TPayload, TMeta, TExtra>, TError>>;
+    fetch(): Promise<QueryResponse<TPayload, TMeta, TExtra>>;
 };
-export type PagingQuery<TPayload, TExtraData = unknown> = Query<TPayload, TExtraData> & {
-    toAllPromise(): Promise<PagingQueryResult<SdkResponse<TPayload, TExtraData>>>;
+export type PagedFetchQuery<TPayload extends JsonValue, TError = KontentSdkError, TMeta = unknown, TExtra = unknown, TPagingExtra = unknown> = Query<TError> & {
+    fetchPageSafe(): Promise<SafeQueryResult<QueryResponse<TPayload, TMeta, TExtra>, TError>>;
+    fetchPage(): Promise<QueryResponse<TPayload, TMeta, TExtra>>;
+    fetchAllPagesSafe(config?: PagingConfig): Promise<SafePagingQueryResult<QueryResponse<TPayload, TMeta, TExtra>, TError, TPagingExtra>>;
+    fetchAllPages(config?: PagingConfig): Promise<PagingQueryResponse<QueryResponse<TPayload, TMeta, TExtra>, TPagingExtra>>;
+    pagesSafe(config?: PagingConfig): AsyncGenerator<SafeQueryResult<QueryResponse<TPayload, TMeta, TExtra>, TError>>;
+    pages(config?: PagingConfig): AsyncGenerator<QueryResponse<TPayload, TMeta, TExtra>>;
 };
-export type SuccessfulHttpResponse<TPayload extends JsonValue, TBodyData extends JsonValue> = Prettify<Extract<HttpResponse<TPayload, TBodyData>, {
-    readonly success: true;
-}>["response"]>;
-export type ResultOfSuccessfulQuery<TQuery extends Query<unknown>> = Extract<Awaited<ReturnType<TQuery["toPromise"]>>, {
+export type MutationQuery<TPayload extends JsonValue, TError = KontentSdkError, TMeta = unknown, TExtra = unknown> = Query<TError> & {
+    executeSafe(): Promise<SafeQueryResult<QueryResponse<TPayload, TMeta, TExtra>, TError>>;
+    execute(): Promise<QueryResponse<TPayload, TMeta, TExtra>>;
+};
+export type PendingNextPageState = {
+    readonly pageSource: "continuationToken";
+    readonly hasNextPage: true;
+    readonly continuationToken: string;
+    readonly nextPageUrl?: never;
+} | {
+    readonly pageSource: "nextPageUrl";
+    readonly hasNextPage: true;
+    readonly continuationToken?: never;
+    readonly nextPageUrl: string;
+} | {
+    readonly pageSource: "firstRequest";
+    readonly hasNextPage: true;
+    readonly continuationToken?: never;
+    readonly nextPageUrl?: never;
+};
+export type SuccessfulHttpResponse<TPayload extends AdapterPayload, TBody extends HttpRequestBody> = Extract<HttpResponse<TPayload, TBody>, {
     readonly success: true;
 }>["response"];
 /**
- * A nomadic result type that represents a success or failure of an operation.
+ * Result type that represents a success or failure of an operation.
  *
  * Ensures that consumers of this library handle both success and failure cases.
  */
-export type QueryResult<TResponse> = (Success & {
-    readonly response: TResponse;
-}) | (Failure & {
+export type SafeQueryResult<TPayload, TError = KontentSdkError> = Success<{
+    readonly response: TPayload;
+}> | Failure<{
     readonly response?: never;
-});
-export type PagingQueryResult<TResponse> = (Success & {
-    readonly responses: TResponse[];
-    readonly lastContinuationToken: string;
-}) | (Failure & {
+}, TError>;
+export type SafePagingQueryResult<TPayload, TError = KontentSdkError, TExtra = unknown> = Success<{
+    readonly responses: readonly TPayload[];
+} & TExtra> | Failure<{
     readonly responses?: never;
-    readonly lastContinuationToken?: never;
-});
-type Success = {
-    readonly success: true;
-    readonly error?: never;
+} & {
+    [K in keyof TExtra]: never;
+}, TError>;
+export type PagingQueryResponse<TPayload, TExtra = unknown> = {
+    readonly responses: readonly TPayload[];
+} & TExtra;
+export type ResolveQueryResult<TPayload extends JsonValue, TError = KontentSdkError, TMeta = unknown, TExtra = unknown> = Promise<SafeQueryResult<QueryResponse<TPayload, TMeta, TExtra>, TError>>;
+export type FetchQueryRequest<TPayload extends JsonValue, TError = KontentSdkError, TMeta = unknown, TExtra = unknown> = Pick<QueryInputData<TPayload, null, TMeta, TExtra, TError>, "config" | "schema" | "sdkInfo" | "mapMetadata" | "abortSignal" | "mapError" | "mapExtraResponseProps"> & RequestDataWithoutBody;
+export type MutationQueryRequest<TPayload extends JsonValue, TBody extends HttpRequestBody, TError = KontentSdkError, TMeta = unknown, TExtra = unknown> = Pick<QueryInputData<TPayload, TBody, TMeta, TExtra, TError>, "config" | "schema" | "sdkInfo" | "mapMetadata" | "abortSignal" | "mapError" | "mapExtraResponseProps"> & {
+    readonly method: MutationHttpMethod;
+} & RequestData<TBody>;
+export type QueryInputData<TPayload extends JsonValue, TBody extends HttpRequestBody, TMeta, TExtra, TError> = {
+    readonly method: HttpMethod;
+    readonly config: SdkConfig;
+    readonly schema: SchemaInput<TPayload>;
+    readonly sdkInfo: SdkInfo;
+    readonly abortSignal?: AbortSignal | undefined;
+    readonly url: string | URL;
+    readonly body: TBody;
+    readonly requestHeaders?: readonly Header[];
+    readonly continuationToken?: string | undefined;
+    readonly authorizationApiKey?: string | undefined;
+} & MetadataMapperConfig<TPayload, TBody, TMeta> & ExtraResponsePropsMapper<TPayload, TBody, TExtra> & ErrorMapper<TError>;
+export type PagingQueryInputData<TPayload extends JsonValue, TBody extends HttpRequestBody, TMeta, TExtra, TPagingExtra, TError> = QueryInputData<TPayload, TBody, TMeta, TExtra, TError> & {
+    readonly mapPagingExtraResponseProps: (responses: readonly QueryResponse<TPayload, TMeta, TExtra>[]) => TPagingExtra;
+};
+export type QueryInspection = Pick<ResolvedQueryData<JsonValue, HttpRequestBody, unknown, unknown, unknown>, "url" | "requestHeaders" | "body" | "method">;
+export type ResolvedQueryData<TPayload extends JsonValue, TBody extends HttpRequestBody, TMeta, TExtra, TError> = {
+    readonly url: URL;
+    readonly requestHeaders: readonly Header[];
+    readonly httpService: HttpService;
+    readonly body: TBody;
+    readonly method: HttpMethod;
+    readonly abortSignal?: AbortSignal | undefined;
+    readonly schema: SchemaInput<TPayload>;
+    readonly responseValidation: SdkConfig["runtimeValidation"];
+} & MetadataMapperConfig<TPayload, TBody, TMeta> & ExtraResponsePropsMapper<TPayload, TBody, TExtra> & ErrorMapper<TError>;
+type MetadataMapperConfig<TPayload extends JsonValue, TBody extends HttpRequestBody, TMeta> = {
+    readonly mapMetadata: MetadataMapper<TPayload, TBody, TMeta>;
+};
+type ExtraResponsePropsMapper<TPayload extends JsonValue, TBody extends HttpRequestBody, TExtra> = {
+    readonly mapExtraResponseProps: (response: HttpResponse<TPayload, TBody>["response"]) => TExtra;
+};
+type ErrorMapper<TError> = {
+    readonly mapError: (error: KontentSdkError) => TError;
+};
+type MetadataMapper<TPayload extends JsonValue, TBody extends HttpRequestBody, TMeta> = (response: SuccessfulHttpResponse<TPayload, TBody>, data: MetadataContext) => TMeta;
+type MetadataContext = {
+    readonly continuationToken: string | undefined;
 };
-type Failure = {
-    readonly success: false;
-    readonly error: CoreSdkError;
+type RequestData<TBody extends HttpRequestBody> = {
+    readonly url: string | URL;
+    readonly body: TBody;
+    readonly requestHeaders?: readonly Header[];
+    readonly continuationToken?: string | undefined;
+    readonly authorizationApiKey?: string | undefined;
 };
+type MutationHttpMethod = PickStringLiteral<HttpMethod, "POST" | "PUT" | "PATCH" | "DELETE">;
+type RequestDataWithoutBody = Omit<RequestData<null>, "body">;
 export {};

package/dist/sdk/sdk-utils.d.ts

@@ -0,0 +1,16 @@
+import type { ZodMiniType } from "zod/mini";
+import type { KontentSdkError } from "../models/error.models.js";
+import type { JsonValue } from "../models/json.models.js";
+import type { Failure } from "../utils/try-catch.utils.js";
+import type { PagedFetchQuery, Query } from "./sdk-models.js";
+/**
+ * Checks if a query is a paging query.
+ */
+export declare function isPagingQuery<TPayload extends JsonValue, TError, TMeta>(query: Query<TError> | PagedFetchQuery<TPayload, TError, TMeta>): query is PagedFetchQuery<TPayload, TError, TMeta>;
+export declare function parseResponse<TPayload extends JsonValue>({ url, payload, schema }: {
+    readonly url: URL;
+    readonly payload: TPayload;
+    readonly schema: ZodMiniType<TPayload>;
+}): Promise<Failure<{
+    readonly response?: never;
+}, KontentSdkError> | undefined>;

package/dist/sdk/sdk-utils.js

@@ -0,0 +1,36 @@
+import { createSdkError } from "../utils/error.utils.js";
+/**
+ * Checks if a query is a paging query.
+ */
+export function isPagingQuery(query) {
+    return ("fetchPage" in query &&
+        "fetchPageSafe" in query &&
+        "fetchAllPages" in query &&
+        "fetchAllPagesSafe" in query &&
+        "pages" in query &&
+        "pagesSafe" in query);
+}
+export async function parseResponse({ url, payload, schema, }) {
+    const { success, error } = await schema.safeParseAsync(payload);
+    if (!success) {
+        return {
+            success: false,
+            error: createSdkError({
+                baseErrorData: {
+                    message: `Failed to parse response payload for '${url.toString()}'`,
+                    url,
+                    retryStrategyOptions: undefined,
+                    retryAttempt: undefined,
+                },
+                details: {
+                    reason: "parsingFailed",
+                    zodError: error,
+                    payload,
+                    url,
+                },
+            }),
+        };
+    }
+    return undefined;
+}
+//# sourceMappingURL=sdk-utils.js.map

package/dist/sdk/sdk-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-utils.js","sourceRoot":"","sources":["../../lib/sdk/sdk-utils.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAIzD;;GAEG;AACH,MAAM,UAAU,aAAa,CAC5B,KAA+D;IAE/D,OAAO,CACN,WAAW,IAAI,KAAK;QACpB,eAAe,IAAI,KAAK;QACxB,eAAe,IAAI,KAAK;QACxB,mBAAmB,IAAI,KAAK;QAC5B,OAAO,IAAI,KAAK;QAChB,WAAW,IAAI,KAAK,CACpB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAA6B,EAC/D,GAAG,EACH,OAAO,EACP,MAAM,GAKN;IACA,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAEhE,IAAI,CAAC,OAAO,EAAE,CAAC;QACd,OAAO;YACN,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,cAAc,CAAC;gBACrB,aAAa,EAAE;oBACd,OAAO,EAAE,yCAAyC,GAAG,CAAC,QAAQ,EAAE,GAAG;oBACnE,GAAG;oBACH,oBAAoB,EAAE,SAAS;oBAC/B,YAAY,EAAE,SAAS;iBACvB;gBACD,OAAO,EAAE;oBACR,MAAM,EAAE,eAAe;oBACvB,QAAQ,EAAE,KAAK;oBACf,OAAO;oBACP,GAAG;iBACH;aACD,CAAC;SACF,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AAClB,CAAC"}

package/dist/sdk/transform/transform-fetch-query.d.ts

@@ -0,0 +1,11 @@
+import type { KontentSdkError } from "../../models/error.models.js";
+import type { JsonValue } from "../../models/json.models.js";
+import type { SchemaInput } from "../../utils/schema.utils.js";
+import type { FetchQuery, QueryResponse, SdkConfig } from "../sdk-models.js";
+export declare function transformFetchQuery<TPayload extends JsonValue, TTransformedPayload extends TPayload, TError extends KontentSdkError, TMeta, TExtra>({ query, transform, transformSchema, mapError, config }: {
+    readonly config: Pick<SdkConfig, "runtimeValidation">;
+    readonly query: FetchQuery<TPayload, TError, TMeta, TExtra>;
+    readonly transform: (response: QueryResponse<TPayload, TMeta, TExtra>) => QueryResponse<TTransformedPayload, TMeta, TExtra>;
+    readonly transformSchema: SchemaInput<TTransformedPayload>;
+    readonly mapError: (error: KontentSdkError) => TError;
+}): FetchQuery<TTransformedPayload, TError, TMeta, TExtra>;

package/dist/sdk/transform/transform-fetch-query.js

@@ -0,0 +1,15 @@
+import { applyTransformOrThrow, applyTransformSafely, createTransformResponse } from "./transform-utils.js";
+export function transformFetchQuery({ query, transform, transformSchema, mapError, config, }) {
+    const transformResponse = createTransformResponse({
+        config,
+        transform,
+        transformSchema,
+        mapError,
+    });
+    return {
+        fetch: async () => applyTransformOrThrow(await query.fetch(), transformResponse),
+        fetchSafe: async () => applyTransformSafely(await query.fetchSafe(), transformResponse),
+        inspect: query.inspect,
+    };
+}
+//# sourceMappingURL=transform-fetch-query.js.map

package/dist/sdk/transform/transform-fetch-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-fetch-query.js","sourceRoot":"","sources":["../../../lib/sdk/transform/transform-fetch-query.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE5G,MAAM,UAAU,mBAAmB,CAMjC,EACD,KAAK,EACL,SAAS,EACT,eAAe,EACf,QAAQ,EACR,MAAM,GAON;IACA,MAAM,iBAAiB,GAAG,uBAAuB,CAAuD;QACvG,MAAM;QACN,SAAS;QACT,eAAe;QACf,QAAQ;KACR,CAAC,CAAC;IAEH,OAAO;QACN,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,qBAAqB,CAAC,MAAM,KAAK,CAAC,KAAK,EAAE,EAAE,iBAAiB,CAAC;QAChF,SAAS,EAAE,KAAK,IAAI,EAAE,CAAC,oBAAoB,CAAC,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,iBAAiB,CAAC;QACvF,OAAO,EAAE,KAAK,CAAC,OAAO;KACtB,CAAC;AACH,CAAC"}

package/dist/sdk/transform/transform-mutation-query.d.ts

@@ -0,0 +1,11 @@
+import type { KontentSdkError } from "../../models/error.models.js";
+import type { JsonValue } from "../../models/json.models.js";
+import type { SchemaInput } from "../../utils/schema.utils.js";
+import type { MutationQuery, QueryResponse, SdkConfig } from "../sdk-models.js";
+export declare function transformMutationQuery<TPayload extends JsonValue, TTransformedPayload extends TPayload, TError extends KontentSdkError, TMeta, TExtra>({ query, transform, transformSchema, mapError, config }: {
+    readonly config: Pick<SdkConfig, "runtimeValidation">;
+    readonly query: MutationQuery<TPayload, TError, TMeta, TExtra>;
+    readonly transform: (response: QueryResponse<TPayload, TMeta, TExtra>) => QueryResponse<TTransformedPayload, TMeta, TExtra>;
+    readonly transformSchema: SchemaInput<TTransformedPayload>;
+    readonly mapError: (error: KontentSdkError) => TError;
+}): MutationQuery<TTransformedPayload, TError, TMeta, TExtra>;

package/dist/sdk/transform/transform-mutation-query.js

@@ -0,0 +1,15 @@
+import { applyTransformOrThrow, applyTransformSafely, createTransformResponse } from "./transform-utils.js";
+export function transformMutationQuery({ query, transform, transformSchema, mapError, config, }) {
+    const transformResponse = createTransformResponse({
+        config,
+        transform,
+        transformSchema,
+        mapError,
+    });
+    return {
+        execute: async () => applyTransformOrThrow(await query.execute(), transformResponse),
+        executeSafe: async () => applyTransformSafely(await query.executeSafe(), transformResponse),
+        inspect: query.inspect,
+    };
+}
+//# sourceMappingURL=transform-mutation-query.js.map

package/dist/sdk/transform/transform-mutation-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-mutation-query.js","sourceRoot":"","sources":["../../../lib/sdk/transform/transform-mutation-query.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE5G,MAAM,UAAU,sBAAsB,CAMpC,EACD,KAAK,EACL,SAAS,EACT,eAAe,EACf,QAAQ,EACR,MAAM,GAON;IACA,MAAM,iBAAiB,GAAG,uBAAuB,CAAuD;QACvG,MAAM;QACN,SAAS;QACT,eAAe;QACf,QAAQ;KACR,CAAC,CAAC;IAEH,OAAO;QACN,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,qBAAqB,CAAC,MAAM,KAAK,CAAC,OAAO,EAAE,EAAE,iBAAiB,CAAC;QACpF,WAAW,EAAE,KAAK,IAAI,EAAE,CAAC,oBAAoB,CAAC,MAAM,KAAK,CAAC,WAAW,EAAE,EAAE,iBAAiB,CAAC;QAC3F,OAAO,EAAE,KAAK,CAAC,OAAO;KACtB,CAAC;AACH,CAAC"}

package/dist/sdk/transform/transform-paged-fetch-query.d.ts

@@ -0,0 +1,11 @@
+import type { KontentSdkError } from "../../models/error.models.js";
+import type { JsonValue } from "../../models/json.models.js";
+import type { SchemaInput } from "../../utils/schema.utils.js";
+import type { PagedFetchQuery, QueryResponse, SdkConfig } from "../sdk-models.js";
+export declare function transformPagedFetchQuery<TPayload extends JsonValue, TTransformedPayload extends TPayload, TError extends KontentSdkError, TMeta, TExtra, TPagingExtra>({ query, transform, transformSchema, mapError, config }: {
+    readonly config: Pick<SdkConfig, "runtimeValidation">;
+    readonly query: PagedFetchQuery<TPayload, TError, TMeta, TExtra, TPagingExtra>;
+    readonly transform: (responses: readonly QueryResponse<TPayload, TMeta, TExtra>[]) => readonly QueryResponse<TTransformedPayload, TMeta, TExtra>[];
+    readonly transformSchema: SchemaInput<TTransformedPayload>;
+    readonly mapError: (error: KontentSdkError) => TError;
+}): PagedFetchQuery<TTransformedPayload, TError, TMeta, TExtra, TPagingExtra>;