@modainteract/moda-interact-shared 5.11.1 → 5.12.0

package/dist/commerce/presentation/node/index.d.ts

@@ -0,0 +1,186 @@
+import { RequestOptions } from 'node:https';
+import { IncomingHttpHeaders } from 'node:http';
+import { Readable } from 'node:stream';
+import { HeadObjectCommandInput, HeadObjectCommandOutput, PutObjectCommandInput } from '@aws-sdk/client-s3';
+import { C as ConversationPreparedProductImage, a as ConversationProductImageSource } from '../../../wrapper-contracts-BcxDQPon.js';
+import 'zod';
+
+/** ARCH-049-BACKGROUND-001: one untrusted source in, one verified immutable image out. */
+declare const SHOP_BRAND_CANVAS: Readonly<{
+    width: 1125;
+    height: 600;
+}>;
+declare const SHOP_BRAND_MAX_SOURCE_BYTES: number;
+declare const SHOP_BRAND_MAX_OUTPUT_BYTES: number;
+declare const SHOP_BRAND_TARGET_OUTPUT_BYTES: number;
+declare const SHOP_BRAND_MAX_INPUT_PIXELS = 40000000;
+type ShopBrandImageRole = "LOGO" | "SQUARE_LOGO" | "COVER_IMAGE";
+type ShopBrandImageMime = "image/jpeg" | "image/png";
+type ShopBrandMediaErrorCode = "INVALID_INPUT" | "UNSAFE_SOURCE" | "DNS_FAILURE" | "DNS_TEMPORARY_FAILURE" | "SOURCE_TIMEOUT" | "SOURCE_HTTP_FAILURE" | "SOURCE_UNAVAILABLE" | "SOURCE_TOO_LARGE" | "UNSUPPORTED_ENCODING" | "INVALID_IMAGE" | "INPUT_PIXELS_EXCEEDED" | "OUTPUT_TOO_LARGE" | "OUTPUT_VERIFICATION_FAILED" | "R2_CONFIGURATION_INVALID" | "R2_UNAVAILABLE" | "R2_OBJECT_MISMATCH" | "PUBLIC_MEDIA_UNAVAILABLE" | "PUBLIC_MEDIA_MISMATCH" | "UNEXPECTED_FAILURE";
+/** The message is a bounded code, not a provider exception or a URL containing credentials. */
+declare class ShopBrandMediaError extends Error {
+    readonly code: ShopBrandMediaErrorCode;
+    readonly retryable: boolean;
+    readonly providerMessage?: string | undefined;
+    constructor(code: ShopBrandMediaErrorCode, retryable?: boolean, providerMessage?: string | undefined);
+}
+/** Bounded diagnostic provenance for provider/library failures; never retain a source URL or common secrets. */
+declare function boundedMediaProviderMessage(error: unknown): string | undefined;
+interface VerifiedBrandImage {
+    bytes: Buffer;
+    contentType: ShopBrandImageMime;
+    width: number;
+    height: number;
+    sizeBytes: number;
+    contentSha256: string;
+}
+interface FetchedBrandSource {
+    bytes: Buffer;
+    /** The response's declared type; never trusted for decoding. */
+    declaredContentType: string | null;
+}
+interface SafeFetcher {
+    fetch(url: string, signal?: AbortSignal): Promise<FetchedBrandSource>;
+}
+interface ImageTransformer {
+    transform(bytes: Buffer, role: ShopBrandImageRole): Promise<VerifiedBrandImage>;
+}
+interface PublicMediaProbe {
+    verify(input: {
+        url: string;
+        image: VerifiedBrandImage;
+    }, signal?: AbortSignal): Promise<void>;
+}
+/** Host-supplied validated credentials; Shared performs no configuration lookup. */
+type ShopBrandR2Credentials = Readonly<{
+    endpoint: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+}>;
+
+declare const MERCHANT_KNOWLEDGE_ACQUISITION_ERROR_CODES: readonly ["INVALID_URL", "DENIED_DESTINATION", "DNS_NO_ADDRESSES", "DNS_TEMPORARY_FAILURE", "DNS_FAILURE", "TOO_MANY_REDIRECTS", "INVALID_REDIRECT", "REQUEST_DEADLINE", "CONNECTION_PEER_MISMATCH", "HTTP_STATUS_TRANSIENT", "HTTP_STATUS_PERMANENT", "UNSUPPORTED_MEDIA_TYPE", "UNSUPPORTED_CONTENT_ENCODING", "BODY_TOO_LARGE", "RESPONSE_READ_FAILED"];
+type MerchantKnowledgeAcquisitionErrorCode = (typeof MERCHANT_KNOWLEDGE_ACQUISITION_ERROR_CODES)[number];
+declare class MerchantKnowledgeAcquisitionError extends Error {
+    readonly code: MerchantKnowledgeAcquisitionErrorCode;
+    readonly retryable: boolean;
+    constructor(code: MerchantKnowledgeAcquisitionErrorCode, message: string, retryable?: boolean);
+}
+interface MerchantKnowledgeResolvedAddress {
+    address: string;
+    family: 4 | 6;
+}
+type MerchantKnowledgeResolver = (hostname: string) => Promise<readonly MerchantKnowledgeResolvedAddress[]>;
+declare function normalizeIpAddress(address: string): string | null;
+declare function isPublicIpAddress(address: string): boolean;
+declare function resolveAllDnsAnswers(hostname: string): Promise<readonly MerchantKnowledgeResolvedAddress[]>;
+declare function resolveAndValidateDestination(hostnameInput: string, resolver?: MerchantKnowledgeResolver): Promise<MerchantKnowledgeResolvedAddress>;
+declare function addressesMatch(left: string, right: string): boolean;
+declare function createPinnedLookup(address: MerchantKnowledgeResolvedAddress): NonNullable<RequestOptions["lookup"]>;
+
+declare const REQUEST_HEADERS: Readonly<{
+    Accept: "image/avif,image/webp,image/png,image/jpeg,image/gif,image/svg+xml,*/*;q=0.2";
+    "Accept-Encoding": "identity";
+    "User-Agent": "ModaInteract-ShopBrandMedia/1.0";
+}>;
+type PinnedImageRequest = Readonly<{
+    hostname: string;
+    path: string;
+    address: MerchantKnowledgeResolvedAddress;
+    servername?: string;
+    headers: typeof REQUEST_HEADERS;
+}>;
+interface ImageHttpResponse {
+    statusCode: number;
+    headers: IncomingHttpHeaders;
+    body: Readable;
+    peerAddress: string;
+}
+type PinnedImageHttpRequest = (input: PinnedImageRequest, signal: AbortSignal) => Promise<ImageHttpResponse>;
+interface SafeImageFetcherOptions {
+    resolveAll?: MerchantKnowledgeResolver;
+    request?: PinnedImageHttpRequest;
+    /** Narrow deployments can prohibit redirects and lower the byte ceiling. */
+    maxRedirects?: number;
+    maxBytes?: number;
+}
+declare function createSafeImageFetcher(options?: SafeImageFetcherOptions): SafeFetcher;
+
+/** Deny SVG constructs capable of loading secondary, unpinned network/file resources. */
+declare function assertSelfContainedSvg(bytes: Buffer): void;
+/** Sharp/libvips is the sole decoder; metadata is a hint, not proof of source MIME. */
+declare function createShopBrandImageTransformer(): ImageTransformer;
+
+type OutreachProductImageTransformer = Readonly<{
+    transform(bytes: Buffer, signal?: AbortSignal): Promise<VerifiedBrandImage>;
+}>;
+/** Standard product preset: preserve the complete product, pad white, and emit only metadata-free JPEG. */
+declare function createOutreachProductImageTransformer(): OutreachProductImageTransformer;
+
+/** Independently re-decode the final *encoded* bytes; neither extensions nor encoder claims suffice. */
+declare function verifyEncodedBrandImage(bytes: Buffer, contentType: ShopBrandImageMime): Promise<VerifiedBrandImage>;
+
+declare const SHOP_BRAND_CACHE_CONTROL = "public, max-age=31536000, immutable";
+/** Narrow injectable S3 boundary; no other R2 operation or credentials reach the processor. */
+interface BrandR2Transport {
+    head(input: HeadObjectCommandInput, signal?: AbortSignal): Promise<HeadObjectCommandOutput>;
+    put(input: PutObjectCommandInput, signal?: AbortSignal): Promise<void>;
+    close?(): void;
+    safeErrorMessage?(error: unknown): string | undefined;
+}
+declare function sanitizeR2ProviderMessage(error: unknown, credentials: ShopBrandR2Credentials): string | undefined;
+declare function createBrandR2S3Transport(credentials: ShopBrandR2Credentials): BrandR2Transport;
+declare function validBucket(bucket: string): boolean;
+/** Shared guarded immutable PUT/HEAD mechanics; each caller supplies its own strict key policy. */
+declare function putGuardedImmutableR2Object(input: Readonly<{
+    transportOrFactory: BrandR2Transport | (() => Promise<BrandR2Transport>);
+    bucket: string;
+    objectKey: string;
+    image: VerifiedBrandImage;
+    acceptsKey: (objectKey: string) => boolean;
+    signal?: AbortSignal;
+    expectedDimensions?: Readonly<{
+        width: number;
+        height: number;
+    }>;
+}>): Promise<void>;
+
+/** A HEAD-only check is insufficient: GET the current custom domain and match the stored bytes. */
+declare function createShopBrandPublicMediaProbe(fetcher: SafeFetcher): PublicMediaProbe;
+
+type ConversationProductImageOmission = 'CONFIGURATION_UNAVAILABLE' | 'UNSAFE_IMAGE_SOURCE' | 'SOURCE_UNAVAILABLE' | 'IMAGE_TRANSFORM_FAILED' | 'R2_UNAVAILABLE' | 'PUBLIC_IMAGE_UNAVAILABLE' | 'MEDIA_DEADLINE';
+type ConversationProductImageStage = 'CONFIGURATION' | 'SOURCE' | 'TRANSFORM' | 'R2' | 'PUBLIC_PROBE' | 'READY';
+type ConversationProductImagePreparation = {
+    kind: 'READY';
+    image: ConversationPreparedProductImage;
+    stage: 'READY';
+    durationMs: number;
+} | {
+    kind: 'OMITTED';
+    reason: ConversationProductImageOmission;
+    stage: ConversationProductImageStage;
+    durationMs: number;
+};
+type ConversationProductImagePreparationInput = {
+    source: ConversationProductImageSource;
+    publicOrigin: string;
+    bucketName: string;
+    r2: ShopBrandR2Credentials;
+    signal?: AbortSignal;
+    /** Original turn deadline in epoch milliseconds. A caller may instead supply an already bounded child signal. */
+    deadlineAt?: number;
+};
+type ConversationProductImagePreparationDependencies = {
+    fetcher?: SafeFetcher;
+    transformer?: {
+        transform(bytes: Buffer, signal?: AbortSignal): Promise<VerifiedBrandImage>;
+    };
+    transportFactory?: (credentials: ShopBrandR2Credentials) => BrandR2Transport;
+    probe?: PublicMediaProbe;
+    now?: () => number;
+};
+declare const isConversationProductObjectKey: (key: string) => boolean;
+declare function conversationProductObjectKey(source: ConversationProductImageSource, contentSha256: string): string;
+/** One optional preparation, no host authorization/config reads, provider sends or logs. */
+declare function prepareConversationProductImage(input: ConversationProductImagePreparationInput, deps?: ConversationProductImagePreparationDependencies): Promise<ConversationProductImagePreparation>;
+
+export { type BrandR2Transport, type ConversationProductImageOmission, type ConversationProductImagePreparation, type ConversationProductImagePreparationDependencies, type ConversationProductImagePreparationInput, type ConversationProductImageStage, type FetchedBrandSource, type ImageHttpResponse, type ImageTransformer, MERCHANT_KNOWLEDGE_ACQUISITION_ERROR_CODES, MerchantKnowledgeAcquisitionError, type MerchantKnowledgeAcquisitionErrorCode, type MerchantKnowledgeResolvedAddress, type MerchantKnowledgeResolver, type OutreachProductImageTransformer, type PinnedImageHttpRequest, type PinnedImageRequest, type PublicMediaProbe, SHOP_BRAND_CACHE_CONTROL, SHOP_BRAND_CANVAS, SHOP_BRAND_MAX_INPUT_PIXELS, SHOP_BRAND_MAX_OUTPUT_BYTES, SHOP_BRAND_MAX_SOURCE_BYTES, SHOP_BRAND_TARGET_OUTPUT_BYTES, type SafeFetcher, type SafeImageFetcherOptions, type ShopBrandImageMime, type ShopBrandImageRole, ShopBrandMediaError, type ShopBrandMediaErrorCode, type ShopBrandR2Credentials, type VerifiedBrandImage, addressesMatch, assertSelfContainedSvg, boundedMediaProviderMessage, conversationProductObjectKey, createBrandR2S3Transport, createOutreachProductImageTransformer, createPinnedLookup, createSafeImageFetcher, createShopBrandImageTransformer, createShopBrandPublicMediaProbe, isConversationProductObjectKey, isPublicIpAddress, validBucket as isValidMediaBucket, normalizeIpAddress, prepareConversationProductImage, putGuardedImmutableR2Object, resolveAllDnsAnswers, resolveAndValidateDestination, sanitizeR2ProviderMessage, verifyEncodedBrandImage };