meridianjs 0.2.5 → 0.2.8

package/dist/providers/googlemaps/adapter.js

@@ -0,0 +1,154 @@
+import { parseRetryAfter } from "../../core/header-parser.js";
+import { ResponseNormalizer } from "../../core/normalizer.js";
+import { MeridianError, SDK_VERSION } from "../../core/types.js";
+import { GoogleMapsPaginationStrategy } from "./pagination.js";
+// Google Maps API-level status codes that indicate specific failure modes.
+const OVER_QUOTA_STATUSES = new Set(["OVER_DAILY_LIMIT", "OVER_QUERY_LIMIT"]);
+const AUTH_STATUSES = new Set(["REQUEST_DENIED"]);
+const VALIDATION_STATUSES = new Set([
+    "INVALID_REQUEST",
+    "MAX_WAYPOINTS_EXCEEDED",
+    "MAX_ROUTE_LENGTH_EXCEEDED",
+    "NOT_FOUND",
+    "ZERO_RESULTS",
+]);
+export class GoogleMapsAdapter {
+    baseUrl;
+    constructor(baseUrl = "https://maps.googleapis.com/maps/api") {
+        this.baseUrl = baseUrl;
+    }
+    buildRequest(input) {
+        const { endpoint, options, authToken, baseUrl } = input;
+        const effectiveBaseUrl = baseUrl ?? this.baseUrl;
+        const url = new URL(endpoint.replace(/^\//, ""), `${effectiveBaseUrl}/`);
+        // API key is passed as a query parameter — this is the standard auth
+        // mechanism for Google Maps Platform REST APIs.
+        url.searchParams.set("key", authToken.token);
+        if (options.query) {
+            for (const [key, value] of Object.entries(options.query)) {
+                // Don't let callers overwrite the auth key.
+                if (key !== "key")
+                    url.searchParams.set(key, String(value));
+            }
+        }
+        const headers = {
+            "User-Agent": `Meridian-SDK/${SDK_VERSION}`,
+            Accept: "application/json",
+            ...options.headers,
+        };
+        let body;
+        const method = options.method ?? "GET";
+        if (options.body && method !== "GET" && method !== "HEAD") {
+            body = JSON.stringify(options.body);
+            headers["Content-Type"] = "application/json";
+        }
+        const built = { url: url.toString(), method, headers };
+        if (body !== undefined) {
+            built.body = body;
+        }
+        return built;
+    }
+    parseResponse(raw) {
+        const rateLimitInfo = this.rateLimitPolicy(raw.headers);
+        const paginationStrategy = this.paginationStrategy();
+        const paginationInfo = ResponseNormalizer.extractPaginationInfo(raw, paginationStrategy);
+        return ResponseNormalizer.normalize(raw, "googlemaps", rateLimitInfo, paginationInfo, [], "1.0.0");
+    }
+    parseError(raw) {
+        if (raw instanceof Error) {
+            const msg = raw.message.toLowerCase();
+            if (msg.includes("fetch") ||
+                msg.includes("network") ||
+                msg.includes("econnreset") ||
+                msg.includes("etimedout") ||
+                msg.includes("enotfound") ||
+                msg.includes("timeout")) {
+                return this.createMeridianError("network", true, "Network request failed. Check your connection and try again.", { originalError: raw.message });
+            }
+        }
+        if (typeof raw === "object" &&
+            raw !== null &&
+            "status" in raw &&
+            typeof raw.status === "number") {
+            return this.parseHttpError(raw);
+        }
+        return this.createMeridianError("provider", false, "An unexpected error occurred", { raw });
+    }
+    parseHttpError(error) {
+        const { status, body, headers } = error;
+        const errorBody = body;
+        // Google Maps often returns 200 with a non-OK status in the body.
+        // When the pipeline surfaces an error, check the body status first.
+        const apiStatus = errorBody?.status ?? errorBody?.error?.status;
+        const message = errorBody?.error_message ?? errorBody?.error?.message;
+        if (apiStatus && OVER_QUOTA_STATUSES.has(apiStatus)) {
+            const retryAfter = this.extractRetryAfter(headers);
+            return this.createMeridianError("rate_limit", true, message ?? "Google Maps quota exceeded. Check your usage limits in Google Cloud Console.", { apiStatus }, retryAfter, 429);
+        }
+        if (apiStatus && AUTH_STATUSES.has(apiStatus)) {
+            return this.createMeridianError("auth", false, message ??
+                "Request denied. Check that your API key is valid and the Maps API is enabled in Google Cloud Console.", { apiStatus }, undefined, 403);
+        }
+        if (apiStatus && VALIDATION_STATUSES.has(apiStatus)) {
+            return this.createMeridianError("validation", false, message ?? `Request failed with status ${apiStatus}.`, { apiStatus }, undefined, 400);
+        }
+        if (status === 400) {
+            return this.createMeridianError("validation", false, message ?? "Bad request. Check the request parameters.", { googleMapsError: errorBody }, undefined, 400);
+        }
+        if (status === 401 || status === 403) {
+            return this.createMeridianError("auth", false, message ??
+                "Authentication failed. Ensure your API key is valid and billing is enabled in Google Cloud Console.", { googleMapsError: errorBody }, undefined, status);
+        }
+        if (status === 404) {
+            return this.createMeridianError("validation", false, message ?? "Resource not found.", { googleMapsError: errorBody }, undefined, 404);
+        }
+        if (status === 429) {
+            const retryAfter = this.extractRetryAfter(headers);
+            return this.createMeridianError("rate_limit", true, message ?? "Rate limit exceeded. Check your quota settings in Google Cloud Console.", { retryAfter: retryAfter?.toISOString() }, retryAfter, 429);
+        }
+        if (status >= 500) {
+            return this.createMeridianError("provider", true, message ?? `Google Maps API returned error ${status}. This may be temporary.`, { status, googleMapsError: errorBody }, undefined, status);
+        }
+        if (status >= 400) {
+            return this.createMeridianError("validation", false, message ?? `Request failed with status ${status}.`, { status, googleMapsError: errorBody }, undefined, status);
+        }
+        return this.createMeridianError("provider", false, `Unexpected response status ${status}.`, { status }, undefined, status);
+    }
+    async authStrategy(config) {
+        const key = config.apiKey ?? config.token;
+        if (!key) {
+            throw this.createMeridianError("auth", false, "Google Maps authentication requires an API key. Set auth.apiKey to your Google Maps Platform API key.", {}, undefined, 401);
+        }
+        return { token: key };
+    }
+    rateLimitPolicy(_headers) {
+        // Google Maps Platform does not expose rate-limit headers in responses.
+        // Quotas are managed in Google Cloud Console (per-day and per-minute limits).
+        return {
+            limit: 3000,
+            remaining: 3000,
+            reset: new Date(Date.now() + 60_000),
+        };
+    }
+    paginationStrategy() {
+        return new GoogleMapsPaginationStrategy();
+    }
+    getIdempotencyConfig() {
+        return {
+            defaultSafeOperations: new Set(["GET", "HEAD", "OPTIONS"]),
+            operationOverrides: new Map(),
+        };
+    }
+    createMeridianError(category, retryable, message, metadata, retryAfter, status) {
+        return new MeridianError(message, category, "googlemaps", retryable, "", metadata, retryAfter, status);
+    }
+    extractRetryAfter(headers) {
+        if (!headers)
+            return undefined;
+        const value = headers instanceof Headers
+            ? headers.get("retry-after")
+            : (Object.entries(headers).find(([k]) => k.toLowerCase() === "retry-after")?.[1] ?? null);
+        return parseRetryAfter(value) ?? undefined;
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/providers/googlemaps/adapter.js.map

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

package/dist/providers/googlemaps/pagination.d.ts

@@ -0,0 +1,17 @@
+import type { PaginationStrategy, RawResponse, RequestOptions } from "../../core/types.js";
+/**
+ * Google Maps Places API uses `next_page_token` in the JSON response body.
+ * The token is passed back as the `pagetoken` query parameter on the next request.
+ * Note: Google requires a short delay before using a page token — the token itself
+ * becomes valid ~2 seconds after the previous response is received.
+ */
+export declare class GoogleMapsPaginationStrategy implements PaginationStrategy {
+    extractCursor(response: RawResponse): string | null;
+    extractTotal(_response: RawResponse): number | null;
+    hasNext(response: RawResponse): boolean;
+    buildNextRequest(endpoint: string, options: RequestOptions, cursor: string): {
+        endpoint: string;
+        options: RequestOptions;
+    };
+}
+//# sourceMappingURL=pagination.d.ts.map

package/dist/providers/googlemaps/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../../src/providers/googlemaps/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE3F;;;;;GAKG;AACH,qBAAa,4BAA6B,YAAW,kBAAkB;IACrE,aAAa,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI;IAUnD,YAAY,CAAC,SAAS,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI;IAInD,OAAO,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO;IAIvC,gBAAgB,CACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,MAAM,GACb;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,cAAc,CAAA;KAAE;CAYjD"}

package/dist/providers/googlemaps/pagination.js

@@ -0,0 +1,36 @@
+/**
+ * Google Maps Places API uses `next_page_token` in the JSON response body.
+ * The token is passed back as the `pagetoken` query parameter on the next request.
+ * Note: Google requires a short delay before using a page token — the token itself
+ * becomes valid ~2 seconds after the previous response is received.
+ */
+export class GoogleMapsPaginationStrategy {
+    extractCursor(response) {
+        if (typeof response.body === "object" && response.body !== null) {
+            const body = response.body;
+            if (typeof body.next_page_token === "string" && body.next_page_token.length > 0) {
+                return body.next_page_token;
+            }
+        }
+        return null;
+    }
+    extractTotal(_response) {
+        return null;
+    }
+    hasNext(response) {
+        return this.extractCursor(response) !== null;
+    }
+    buildNextRequest(endpoint, options, cursor) {
+        return {
+            endpoint,
+            options: {
+                ...options,
+                query: {
+                    ...options.query,
+                    pagetoken: cursor,
+                },
+            },
+        };
+    }
+}
+//# sourceMappingURL=pagination.js.map

package/dist/providers/googlemaps/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../../src/providers/googlemaps/pagination.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,OAAO,4BAA4B;IACvC,aAAa,CAAC,QAAqB;QACjC,IAAI,OAAO,QAAQ,CAAC,IAAI,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YAChE,MAAM,IAAI,GAAG,QAAQ,CAAC,IAA+B,CAAC;YACtD,IAAI,OAAO,IAAI,CAAC,eAAe,KAAK,QAAQ,IAAI,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAChF,OAAO,IAAI,CAAC,eAAe,CAAC;YAC9B,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,YAAY,CAAC,SAAsB;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,CAAC,QAAqB;QAC3B,OAAO,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAC/C,CAAC;IAED,gBAAgB,CACd,QAAgB,EAChB,OAAuB,EACvB,MAAc;QAEd,OAAO;YACL,QAAQ;YACR,OAAO,EAAE;gBACP,GAAG,OAAO;gBACV,KAAK,EAAE;oBACL,GAAG,OAAO,CAAC,KAAK;oBAChB,SAAS,EAAE,MAAM;iBAClB;aACF;SACF,CAAC;IACJ,CAAC;CACF"}

package/dist/providers/s3/adapter.d.ts

@@ -0,0 +1,37 @@
+import type { AdapterInput, AuthConfig, AuthToken, BuiltRequest, IdempotencyConfig, NormalizedResponse, PaginationStrategy, ProviderAdapter, RateLimitInfo, RawResponse } from "../../core/types.js";
+import { MeridianError } from "../../core/types.js";
+/**
+ * S3-compatible object storage (AWS S3, Cloudflare R2, and other S3-API stores)
+ * authenticates every request with AWS Signature Version 4 — there's no bearer
+ * token or static API key header. Each call is signed in `buildRequest` using
+ * the access key / secret key (and, for R2, region `"auto"`) supplied via
+ * `auth.custom`. Responses are XML, not JSON; pagination and error parsing
+ * extract the handful of fields they need from that XML directly.
+ *
+ * Configure with `auth.username`/`auth.password` (access key / secret key) and
+ * `auth.custom = { region, endpoint?, sessionToken? }`. For R2, set
+ * `auth.custom.region = "auto"` and `auth.custom.endpoint` to your account's
+ * `https://<account_id>.r2.cloudflarestorage.com` URL (or pass it as `baseUrl`
+ * in the provider config).
+ */
+export declare class S3Adapter implements ProviderAdapter {
+    private baseUrl;
+    constructor(baseUrl?: string);
+    buildRequest(input: AdapterInput): BuiltRequest;
+    parseResponse(raw: RawResponse): NormalizedResponse;
+    parseError(raw: unknown): MeridianError;
+    private parseHttpError;
+    authStrategy(config: AuthConfig): Promise<AuthToken>;
+    rateLimitPolicy(_headers: Headers): RateLimitInfo;
+    paginationStrategy(): PaginationStrategy;
+    getIdempotencyConfig(): IdempotencyConfig;
+    /**
+     * Verifies an S3 Event Notification delivered via SNS/EventBridge webhook —
+     * an HMAC-SHA256 digest of the raw request body, hex-encoded, keyed by a
+     * shared secret configured on the destination (S3 itself does not sign
+     * notifications; this supports the common "shared secret" relay pattern).
+     */
+    verifyWebhook(payload: string | Buffer, signature: string, secret: string): boolean;
+    private createMeridianError;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/providers/s3/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/providers/s3/adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,SAAS,EACT,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAoB,aAAa,EAAe,MAAM,qBAAqB,CAAC;AA+CnF;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAU,YAAW,eAAe;IAC/C,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,SAA8B;IAIjD,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY;IAqC/C,aAAa,CAAC,GAAG,EAAE,WAAW,GAAG,kBAAkB;IAOnD,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa;IAkCvC,OAAO,CAAC,cAAc;IAkGhB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;IA8B1D,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,aAAa;IASjD,kBAAkB,IAAI,kBAAkB;IAIxC,oBAAoB,IAAI,iBAAiB;IAOzC;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAYnF,OAAO,CAAC,mBAAmB;CAU5B"}

package/dist/providers/s3/adapter.js

@@ -0,0 +1,206 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { ResponseNormalizer } from "../../core/normalizer.js";
+import { IdempotencyLevel, MeridianError, SDK_VERSION } from "../../core/types.js";
+import { S3PaginationStrategy } from "./pagination.js";
+import { signSigV4 } from "./sigv4.js";
+function extractXmlField(xml, tag) {
+    const match = xml.match(new RegExp(`<${tag}>([^<]*)</${tag}>`));
+    return match?.[1] ?? null;
+}
+/**
+ * The auth token carries SigV4 credentials JSON-encoded (see `authStrategy`).
+ * Falls back to treating an opaque token string as the access key ID — this
+ * keeps `buildRequest` resilient to non-JSON tokens (e.g. generic contract
+ * tests that pass a placeholder string) without producing a usable signature.
+ */
+function parseSigV4Credentials(token) {
+    try {
+        return JSON.parse(token);
+    }
+    catch {
+        return { accessKeyId: token, secretAccessKey: "", region: "us-east-1", service: "s3" };
+    }
+}
+/** Parses S3/R2's XML error body into a plain object, when present. */
+function parseS3ErrorXml(body) {
+    if (typeof body !== "string" || !body.includes("<Error>")) {
+        return typeof body === "object" && body !== null ? body : undefined;
+    }
+    const result = {};
+    const code = extractXmlField(body, "Code");
+    const message = extractXmlField(body, "Message");
+    const requestId = extractXmlField(body, "RequestId");
+    const resource = extractXmlField(body, "Resource");
+    if (code !== null)
+        result.Code = code;
+    if (message !== null)
+        result.Message = message;
+    if (requestId !== null)
+        result.RequestId = requestId;
+    if (resource !== null)
+        result.Resource = resource;
+    return result;
+}
+/**
+ * S3-compatible object storage (AWS S3, Cloudflare R2, and other S3-API stores)
+ * authenticates every request with AWS Signature Version 4 — there's no bearer
+ * token or static API key header. Each call is signed in `buildRequest` using
+ * the access key / secret key (and, for R2, region `"auto"`) supplied via
+ * `auth.custom`. Responses are XML, not JSON; pagination and error parsing
+ * extract the handful of fields they need from that XML directly.
+ *
+ * Configure with `auth.username`/`auth.password` (access key / secret key) and
+ * `auth.custom = { region, endpoint?, sessionToken? }`. For R2, set
+ * `auth.custom.region = "auto"` and `auth.custom.endpoint` to your account's
+ * `https://<account_id>.r2.cloudflarestorage.com` URL (or pass it as `baseUrl`
+ * in the provider config).
+ */
+export class S3Adapter {
+    baseUrl;
+    constructor(baseUrl = "https://s3.amazonaws.com/") {
+        this.baseUrl = baseUrl;
+    }
+    buildRequest(input) {
+        const { endpoint, options, authToken, baseUrl } = input;
+        const effectiveBaseUrl = baseUrl ?? this.baseUrl;
+        const url = new URL(endpoint.replace(/^\//, ""), effectiveBaseUrl);
+        if (options.query) {
+            for (const [key, value] of Object.entries(options.query)) {
+                url.searchParams.set(key, String(value));
+            }
+        }
+        const credentials = parseSigV4Credentials(authToken.token);
+        const method = options.method ?? "GET";
+        let body;
+        const baseHeaders = {
+            "User-Agent": `Meridian-SDK/${SDK_VERSION}`,
+            ...options.headers,
+        };
+        if (options.body && method !== "GET" && method !== "HEAD") {
+            body = typeof options.body === "string" ? options.body : JSON.stringify(options.body);
+            baseHeaders["Content-Type"] ??= "application/octet-stream";
+        }
+        const signed = signSigV4(body !== undefined
+            ? { method, url, headers: baseHeaders, body, credentials }
+            : { method, url, headers: baseHeaders, credentials });
+        const built = { url: url.toString(), method, headers: signed.headers };
+        if (body !== undefined) {
+            built.body = body;
+        }
+        return built;
+    }
+    parseResponse(raw) {
+        const rateLimitInfo = this.rateLimitPolicy(raw.headers);
+        const paginationStrategy = this.paginationStrategy();
+        const paginationInfo = ResponseNormalizer.extractPaginationInfo(raw, paginationStrategy);
+        return ResponseNormalizer.normalize(raw, "s3", rateLimitInfo, paginationInfo, [], "1.0.0");
+    }
+    parseError(raw) {
+        if (raw instanceof Error) {
+            const msg = raw.message.toLowerCase();
+            if (msg.includes("fetch") ||
+                msg.includes("network") ||
+                msg.includes("econnreset") ||
+                msg.includes("etimedout") ||
+                msg.includes("enotfound") ||
+                msg.includes("timeout")) {
+                return this.createMeridianError("network", true, "Network request failed. Check your connection and try again.", { originalError: raw.message });
+            }
+        }
+        if (typeof raw === "object" &&
+            raw !== null &&
+            "status" in raw &&
+            typeof raw.status === "number") {
+            return this.parseHttpError(raw);
+        }
+        return this.createMeridianError("provider", false, "An unexpected error occurred", { raw });
+    }
+    parseHttpError(error) {
+        const { status } = error;
+        const errorBody = parseS3ErrorXml(error.body);
+        const errorMessage = errorBody?.Message;
+        const metadata = { code: errorBody?.Code, requestId: errorBody?.RequestId };
+        if (status === 401 || status === 403) {
+            return this.createMeridianError("auth", false, errorMessage ??
+                "Authentication failed. Check your access key ID, secret access key, and signing region.", metadata, undefined, status);
+        }
+        if (status === 404) {
+            return this.createMeridianError("validation", false, errorMessage ?? "Bucket or object not found.", metadata, undefined, 404);
+        }
+        if (status === 409 || status === 412 || status === 422) {
+            return this.createMeridianError("validation", false, errorMessage ?? "Request validation failed.", metadata, undefined, status);
+        }
+        if (status === 429 || (status === 503 && errorBody?.Code === "SlowDown")) {
+            return this.createMeridianError("rate_limit", true, errorMessage ?? "Request rate exceeded. Please slow down and retry.", metadata, undefined, status);
+        }
+        if (status === 400) {
+            return this.createMeridianError("validation", false, errorMessage ?? "Request validation failed.", metadata, undefined, 400);
+        }
+        if (status >= 500) {
+            return this.createMeridianError("provider", true, errorMessage ?? `S3 API returned error ${status}. This may be temporary.`, metadata, undefined, status);
+        }
+        if (status >= 400) {
+            return this.createMeridianError("validation", false, errorMessage ?? `Request failed with status ${status}.`, metadata, undefined, status);
+        }
+        return this.createMeridianError("provider", false, `Unexpected response status ${status}.`, metadata, undefined, status);
+    }
+    async authStrategy(config) {
+        const accessKeyId = config.username ?? config.apiKey ?? config.clientId;
+        const secretAccessKey = config.password ?? config.apiSecret ?? config.clientSecret;
+        const region = config.custom?.region ?? "us-east-1";
+        const sessionToken = config.custom?.sessionToken ?? config.refreshToken;
+        if (!accessKeyId || !secretAccessKey) {
+            throw this.createMeridianError("auth", false, "S3 authentication requires an access key ID and secret access key. " +
+                "Set auth.username (access key ID) + auth.password (secret access key), " +
+                'and optionally auth.custom = { region, sessionToken } (use region: "auto" for R2).', {}, undefined, 401);
+        }
+        const credentials = {
+            accessKeyId,
+            secretAccessKey,
+            region,
+            service: "s3",
+            ...(sessionToken ? { sessionToken } : {}),
+        };
+        return { token: JSON.stringify(credentials) };
+    }
+    rateLimitPolicy(_headers) {
+        // S3 does not publish rate-limit headers; it signals throttling via 503 SlowDown.
+        return {
+            limit: 100,
+            remaining: 100,
+            reset: new Date(Date.now() + 60_000),
+        };
+    }
+    paginationStrategy() {
+        return new S3PaginationStrategy();
+    }
+    getIdempotencyConfig() {
+        return {
+            defaultSafeOperations: new Set(["GET", "HEAD", "OPTIONS"]),
+            operationOverrides: new Map([["PUT", IdempotencyLevel.IDEMPOTENT]]),
+        };
+    }
+    /**
+     * Verifies an S3 Event Notification delivered via SNS/EventBridge webhook —
+     * an HMAC-SHA256 digest of the raw request body, hex-encoded, keyed by a
+     * shared secret configured on the destination (S3 itself does not sign
+     * notifications; this supports the common "shared secret" relay pattern).
+     */
+    verifyWebhook(payload, signature, secret) {
+        const expected = createHmac("sha256", secret).update(payload).digest("hex");
+        try {
+            const a = Buffer.from(expected);
+            const b = Buffer.from(signature);
+            if (a.length !== b.length)
+                return false;
+            return timingSafeEqual(a, b);
+        }
+        catch {
+            return false;
+        }
+    }
+    createMeridianError(category, retryable, message, metadata, retryAfter, status) {
+        return new MeridianError(message, category, "s3", retryable, "", metadata, retryAfter, status);
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/providers/s3/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/providers/s3/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAa9D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAyB,SAAS,EAAE,MAAM,YAAY,CAAC;AAS9D,SAAS,eAAe,CAAC,GAAW,EAAE,GAAW;IAC/C,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,IAAI,GAAG,aAAa,GAAG,GAAG,CAAC,CAAC,CAAC;IAChE,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,SAAS,qBAAqB,CAAC,KAAa;IAC1C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAqB,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACzF,CAAC;AACH,CAAC;AAED,uEAAuE;AACvE,SAAS,eAAe,CAAC,IAAa;IACpC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1D,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,CAAE,IAAoB,CAAC,CAAC,CAAC,SAAS,CAAC;IACvF,CAAC;IACD,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACjD,MAAM,SAAS,GAAG,eAAe,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IACrD,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACnD,IAAI,IAAI,KAAK,IAAI;QAAE,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;IACtC,IAAI,OAAO,KAAK,IAAI;QAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;IAC/C,IAAI,SAAS,KAAK,IAAI;QAAE,MAAM,CAAC,SAAS,GAAG,SAAS,CAAC;IACrD,IAAI,QAAQ,KAAK,IAAI;QAAE,MAAM,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAClD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,SAAS;IACZ,OAAO,CAAS;IAExB,YAAY,OAAO,GAAG,2BAA2B;QAC/C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,YAAY,CAAC,KAAmB;QAC9B,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;QACxD,MAAM,gBAAgB,GAAG,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC;QACjD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC;QAEnE,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;QAED,MAAM,WAAW,GAAG,qBAAqB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC3D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC;QAEvC,IAAI,IAAwB,CAAC;QAC7B,MAAM,WAAW,GAA2B;YAC1C,YAAY,EAAE,gBAAgB,WAAW,EAAE;YAC3C,GAAG,OAAO,CAAC,OAAO;SACnB,CAAC;QACF,IAAI,OAAO,CAAC,IAAI,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;YAC1D,IAAI,GAAG,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACtF,WAAW,CAAC,cAAc,CAAC,KAAK,0BAA0B,CAAC;QAC7D,CAAC;QAED,MAAM,MAAM,GAAG,SAAS,CACtB,IAAI,KAAK,SAAS;YAChB,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE;YAC1D,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,CACvD,CAAC;QAEF,MAAM,KAAK,GAAiB,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;QACrF,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;QACpB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,aAAa,CAAC,GAAgB;QAC5B,MAAM,aAAa,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACxD,MAAM,kBAAkB,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACrD,MAAM,cAAc,GAAG,kBAAkB,CAAC,qBAAqB,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;QACzF,OAAO,kBAAkB,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,aAAa,EAAE,cAAc,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IAC7F,CAAC;IAED,UAAU,CAAC,GAAY;QACrB,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;YACzB,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;YACtC,IACE,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC;gBACrB,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC;gBACvB,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC;gBAC1B,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC;gBACzB,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC;gBACzB,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,EACvB,CAAC;gBACD,OAAO,IAAI,CAAC,mBAAmB,CAC7B,SAAS,EACT,IAAI,EACJ,8DAA8D,EAC9D,EAAE,aAAa,EAAE,GAAG,CAAC,OAAO,EAAE,CAC/B,CAAC;YACJ,CAAC;QACH,CAAC;QAED,IACE,OAAO,GAAG,KAAK,QAAQ;YACvB,GAAG,KAAK,IAAI;YACZ,QAAQ,IAAI,GAAG;YACf,OAAQ,GAA+B,CAAC,MAAM,KAAK,QAAQ,EAC3D,CAAC;YACD,OAAO,IAAI,CAAC,cAAc,CACxB,GAAqF,CACtF,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAC,mBAAmB,CAAC,UAAU,EAAE,KAAK,EAAE,8BAA8B,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IAC9F,CAAC;IAEO,cAAc,CAAC,KAItB;QACC,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;QACzB,MAAM,SAAS,GAAG,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9C,MAAM,YAAY,GAAG,SAAS,EAAE,OAAO,CAAC;QACxC,MAAM,QAAQ,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;QAE5E,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;YACrC,OAAO,IAAI,CAAC,mBAAmB,CAC7B,MAAM,EACN,KAAK,EACL,YAAY;gBACV,yFAAyF,EAC3F,QAAQ,EACR,SAAS,EACT,MAAM,CACP,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;YACnB,OAAO,IAAI,CAAC,mBAAmB,CAC7B,YAAY,EACZ,KAAK,EACL,YAAY,IAAI,6BAA6B,EAC7C,QAAQ,EACR,SAAS,EACT,GAAG,CACJ,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;YACvD,OAAO,IAAI,CAAC,mBAAmB,CAC7B,YAAY,EACZ,KAAK,EACL,YAAY,IAAI,4BAA4B,EAC5C,QAAQ,EACR,SAAS,EACT,MAAM,CACP,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,SAAS,EAAE,IAAI,KAAK,UAAU,CAAC,EAAE,CAAC;YACzE,OAAO,IAAI,CAAC,mBAAmB,CAC7B,YAAY,EACZ,IAAI,EACJ,YAAY,IAAI,oDAAoD,EACpE,QAAQ,EACR,SAAS,EACT,MAAM,CACP,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;YACnB,OAAO,IAAI,CAAC,mBAAmB,CAC7B,YAAY,EACZ,KAAK,EACL,YAAY,IAAI,4BAA4B,EAC5C,QAAQ,EACR,SAAS,EACT,GAAG,CACJ,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;YAClB,OAAO,IAAI,CAAC,mBAAmB,CAC7B,UAAU,EACV,IAAI,EACJ,YAAY,IAAI,yBAAyB,MAAM,0BAA0B,EACzE,QAAQ,EACR,SAAS,EACT,MAAM,CACP,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;YAClB,OAAO,IAAI,CAAC,mBAAmB,CAC7B,YAAY,EACZ,KAAK,EACL,YAAY,IAAI,8BAA8B,MAAM,GAAG,EACvD,QAAQ,EACR,SAAS,EACT,MAAM,CACP,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAC,mBAAmB,CAC7B,UAAU,EACV,KAAK,EACL,8BAA8B,MAAM,GAAG,EACvC,QAAQ,EACR,SAAS,EACT,MAAM,CACP,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,MAAkB;QACnC,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,QAAQ,CAAC;QACxE,MAAM,eAAe,GAAG,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,YAAY,CAAC;QACnF,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,IAAI,WAAW,CAAC;QACpD,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,IAAI,MAAM,CAAC,YAAY,CAAC;QAExE,IAAI,CAAC,WAAW,IAAI,CAAC,eAAe,EAAE,CAAC;YACrC,MAAM,IAAI,CAAC,mBAAmB,CAC5B,MAAM,EACN,KAAK,EACL,qEAAqE;gBACnE,yEAAyE;gBACzE,oFAAoF,EACtF,EAAE,EACF,SAAS,EACT,GAAG,CACJ,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAqB;YACpC,WAAW;YACX,eAAe;YACf,MAAM;YACN,OAAO,EAAE,IAAI;YACb,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1C,CAAC;QAEF,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC;IAChD,CAAC;IAED,eAAe,CAAC,QAAiB;QAC/B,kFAAkF;QAClF,OAAO;YACL,KAAK,EAAE,GAAG;YACV,SAAS,EAAE,GAAG;YACd,KAAK,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC;SACrC,CAAC;IACJ,CAAC;IAED,kBAAkB;QAChB,OAAO,IAAI,oBAAoB,EAAE,CAAC;IACpC,CAAC;IAED,oBAAoB;QAClB,OAAO;YACL,qBAAqB,EAAE,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;YAC1D,kBAAkB,EAAE,IAAI,GAAG,CAA2B,CAAC,CAAC,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAC,CAAC;SAC9F,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,aAAa,CAAC,OAAwB,EAAE,SAAiB,EAAE,MAAc;QACvE,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5E,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAChC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACjC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;gBAAE,OAAO,KAAK,CAAC;YACxC,OAAO,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAEO,mBAAmB,CACzB,QAAmC,EACnC,SAAkB,EAClB,OAAe,EACf,QAAkC,EAClC,UAAiB,EACjB,MAAe;QAEf,OAAO,IAAI,aAAa,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IACjG,CAAC;CACF"}

package/dist/providers/s3/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./adapter.js";
+export * from "./pagination.js";
+export * from "./sigv4.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/s3/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/s3/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC"}

package/dist/providers/s3/index.js

@@ -0,0 +1,4 @@
+export * from "./adapter.js";
+export * from "./pagination.js";
+export * from "./sigv4.js";
+//# sourceMappingURL=index.js.map

package/dist/providers/s3/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/providers/s3/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC"}

package/dist/providers/s3/pagination.d.ts

@@ -0,0 +1,18 @@
+import type { PaginationStrategy, RawResponse, RequestOptions } from "../../core/types.js";
+/**
+ * S3 / R2's `ListObjectsV2` returns XML with `IsTruncated` and, when there are
+ * more results, a `NextContinuationToken` — fed back as the `continuation-token`
+ * query parameter. The SDK's HTTP layer hands us the raw XML string as the body
+ * for non-JSON responses.
+ */
+export declare class S3PaginationStrategy implements PaginationStrategy {
+    extractCursor(response: RawResponse): string | null;
+    extractTotal(response: RawResponse): number | null;
+    hasNext(response: RawResponse): boolean;
+    buildNextRequest(endpoint: string, options: RequestOptions, cursor: string): {
+        endpoint: string;
+        options: RequestOptions;
+    };
+    private bodyAsXml;
+}
+//# sourceMappingURL=pagination.d.ts.map

package/dist/providers/s3/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../../src/providers/s3/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAY3F;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,kBAAkB;IAC7D,aAAa,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI;IAMnD,YAAY,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI;IASlD,OAAO,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO;IAMvC,gBAAgB,CACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,MAAM,GACb;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,cAAc,CAAA;KAAE;IAahD,OAAO,CAAC,SAAS;CAMlB"}

package/dist/providers/s3/pagination.js

@@ -0,0 +1,58 @@
+/**
+ * Extracts a top-level XML element's text content via a narrow regex match.
+ * S3's ListObjectsV2 response is flat enough (no nested elements share these
+ * tag names) that a full XML parser isn't warranted here.
+ */
+function extractXmlField(xml, tag) {
+    const match = xml.match(new RegExp(`<${tag}>([^<]*)</${tag}>`));
+    return match?.[1] ?? null;
+}
+/**
+ * S3 / R2's `ListObjectsV2` returns XML with `IsTruncated` and, when there are
+ * more results, a `NextContinuationToken` — fed back as the `continuation-token`
+ * query parameter. The SDK's HTTP layer hands us the raw XML string as the body
+ * for non-JSON responses.
+ */
+export class S3PaginationStrategy {
+    extractCursor(response) {
+        const xml = this.bodyAsXml(response);
+        if (!xml)
+            return null;
+        return extractXmlField(xml, "NextContinuationToken");
+    }
+    extractTotal(response) {
+        const xml = this.bodyAsXml(response);
+        if (!xml)
+            return null;
+        const keyCount = extractXmlField(xml, "KeyCount");
+        if (keyCount === null)
+            return null;
+        const parsed = Number.parseInt(keyCount, 10);
+        return Number.isNaN(parsed) ? null : parsed;
+    }
+    hasNext(response) {
+        const xml = this.bodyAsXml(response);
+        if (!xml)
+            return false;
+        return extractXmlField(xml, "IsTruncated") === "true";
+    }
+    buildNextRequest(endpoint, options, cursor) {
+        return {
+            endpoint,
+            options: {
+                ...options,
+                query: {
+                    ...options.query,
+                    "continuation-token": cursor,
+                },
+            },
+        };
+    }
+    bodyAsXml(response) {
+        if (typeof response.body === "string" && response.body.includes("<ListBucketResult")) {
+            return response.body;
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=pagination.js.map

package/dist/providers/s3/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../../src/providers/s3/pagination.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,SAAS,eAAe,CAAC,GAAW,EAAE,GAAW;IAC/C,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,IAAI,GAAG,aAAa,GAAG,GAAG,CAAC,CAAC,CAAC;IAChE,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,oBAAoB;IAC/B,aAAa,CAAC,QAAqB;QACjC,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACrC,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QACtB,OAAO,eAAe,CAAC,GAAG,EAAE,uBAAuB,CAAC,CAAC;IACvD,CAAC;IAED,YAAY,CAAC,QAAqB;QAChC,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACrC,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QACtB,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QAClD,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QACnC,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC7C,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9C,CAAC;IAED,OAAO,CAAC,QAAqB;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACrC,IAAI,CAAC,GAAG;YAAE,OAAO,KAAK,CAAC;QACvB,OAAO,eAAe,CAAC,GAAG,EAAE,aAAa,CAAC,KAAK,MAAM,CAAC;IACxD,CAAC;IAED,gBAAgB,CACd,QAAgB,EAChB,OAAuB,EACvB,MAAc;QAEd,OAAO;YACL,QAAQ;YACR,OAAO,EAAE;gBACP,GAAG,OAAO;gBACV,KAAK,EAAE;oBACL,GAAG,OAAO,CAAC,KAAK;oBAChB,oBAAoB,EAAE,MAAM;iBAC7B;aACF;SACF,CAAC;IACJ,CAAC;IAEO,SAAS,CAAC,QAAqB;QACrC,IAAI,OAAO,QAAQ,CAAC,IAAI,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC;YACrF,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/providers/s3/sigv4.d.ts

@@ -0,0 +1,29 @@
+export interface SigV4Credentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    region: string;
+    service?: string;
+    sessionToken?: string;
+}
+export interface SigV4SignInput {
+    method: string;
+    url: URL;
+    headers: Record<string, string>;
+    body?: string;
+    credentials: SigV4Credentials;
+    /** Override the signing instant — primarily for deterministic tests. */
+    date?: Date;
+}
+export interface SigV4SignedRequest {
+    headers: Record<string, string>;
+}
+/**
+ * Signs a request per AWS Signature Version 4 (the scheme used by S3, R2, and
+ * other S3-compatible object stores). Returns the headers to attach — including
+ * `Authorization`, `x-amz-date`, `x-amz-content-sha256`, and `host` — that make
+ * the request authenticate as the given credentials.
+ *
+ * Reference: https://docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html
+ */
+export declare function signSigV4(input: SigV4SignInput): SigV4SignedRequest;
+//# sourceMappingURL=sigv4.d.ts.map

package/dist/providers/s3/sigv4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sigv4.d.ts","sourceRoot":"","sources":["../../../src/providers/s3/sigv4.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,GAAG,CAAC;IACT,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,gBAAgB,CAAC;IAC9B,wEAAwE;IACxE,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AA4DD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,kBAAkB,CAuDnE"}