@adcp/sdk 16.0.0-beta.3 → 16.0.0-beta.4

package/dist/lib/reporting/s3/index.d.mts

@@ -1,34 +0,0 @@
-import { type S3Client } from '@aws-sdk/client-s3';
-import type { ReportingRowObjectProviderV1 } from '../ledger/row-storage-object.mjs';
-/**
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export interface CreateS3ReportingRowObjectProviderOptionsV1 {
-    /** Official client used by bindings without a `credentialRef`. */
-    client?: S3Client;
-    /**
-     * Official clients keyed by `credentialRef`. This map is the closed set of
-     * references a binding may name; an unknown reference fails `UNSAFE_BINDING`.
-     * Endpoint, region, credentials and path style all come from these clients,
-     * never from binding locations.
-     */
-    clients?: Readonly<Record<string, S3Client>>;
-}
-/**
- * Amazon S3 (and S3-compatible) row-object provider (`@adcp/sdk/reporting/s3`).
- *
- * Inject official `S3Client`s configured by the host (region, endpoint,
- * credentials). Bindings use `location: { bucket, region? }`; when `region` is
- * set the probe requires the selected client to be configured for it.
- *
- * Writes use `PutObject` with `If-None-Match: *`. Bucket versioning must be
- * enabled: the recorded native version is the write-unique `VersionId`, and every
- * read and delete is pinned to it, so a delayed delete can never remove a later
- * write that re-created identical bytes at the same key (ETags are content-derived
- * and cannot fence that). The probe refuses unversioned or suspended buckets.
- * Because S3-compatible stores may silently ignore `If-None-Match`, the probe
- * also proves create-only behaviour empirically before any binding is used.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export declare function createS3ReportingRowObjectProviderV1(options: CreateS3ReportingRowObjectProviderOptionsV1): ReportingRowObjectProviderV1;

package/dist/lib/reporting/s3/index.d.ts

@@ -1,34 +0,0 @@
-import { type S3Client } from '@aws-sdk/client-s3';
-import type { ReportingRowObjectProviderV1 } from '../ledger/row-storage-object';
-/**
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export interface CreateS3ReportingRowObjectProviderOptionsV1 {
-    /** Official client used by bindings without a `credentialRef`. */
-    client?: S3Client;
-    /**
-     * Official clients keyed by `credentialRef`. This map is the closed set of
-     * references a binding may name; an unknown reference fails `UNSAFE_BINDING`.
-     * Endpoint, region, credentials and path style all come from these clients,
-     * never from binding locations.
-     */
-    clients?: Readonly<Record<string, S3Client>>;
-}
-/**
- * Amazon S3 (and S3-compatible) row-object provider (`@adcp/sdk/reporting/s3`).
- *
- * Inject official `S3Client`s configured by the host (region, endpoint,
- * credentials). Bindings use `location: { bucket, region? }`; when `region` is
- * set the probe requires the selected client to be configured for it.
- *
- * Writes use `PutObject` with `If-None-Match: *`. Bucket versioning must be
- * enabled: the recorded native version is the write-unique `VersionId`, and every
- * read and delete is pinned to it, so a delayed delete can never remove a later
- * write that re-created identical bytes at the same key (ETags are content-derived
- * and cannot fence that). The probe refuses unversioned or suspended buckets.
- * Because S3-compatible stores may silently ignore `If-None-Match`, the probe
- * also proves create-only behaviour empirically before any binding is used.
- *
- * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
- */
-export declare function createS3ReportingRowObjectProviderV1(options: CreateS3ReportingRowObjectProviderOptionsV1): ReportingRowObjectProviderV1;

package/dist/lib/reporting/s3/index.js

@@ -1,347 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var s3_exports = {};
-__export(s3_exports, {
-  createS3ReportingRowObjectProviderV1: () => createS3ReportingRowObjectProviderV1
-});
-module.exports = __toCommonJS(s3_exports);
-var import_node_crypto = require("node:crypto");
-var import_client_s3 = require("@aws-sdk/client-s3");
-var import_row_storage_errors = require('../ledger/row-storage-errors.js');
-var import_row_storage_provider_io = require('../ledger/row-storage-provider-io.js');
-const BUCKET = /^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/;
-const REGION = /^[a-z0-9][a-z0-9-]{0,30}[a-z0-9]$/;
-const VERSION_ID = /^[\x21\x23-\x7e]{1,1024}$/;
-function statusOf(error) {
-  const status = Number(error?.$metadata?.httpStatusCode);
-  return Number.isInteger(status) ? status : void 0;
-}
-function nameOf(error) {
-  const value = error?.name ?? error?.Code;
-  return typeof value === "string" ? value : "";
-}
-const isPreconditionFailed = (error) => statusOf(error) === 412 || nameOf(error) === "PreconditionFailed";
-const isConditionalConflict = (error) => statusOf(error) === 409 || nameOf(error) === "ConditionalRequestConflict";
-const isNotFound = (error) => statusOf(error) === 404 || ["NoSuchKey", "NotFound", "NoSuchVersion", "NoSuchBucket"].includes(nameOf(error));
-const isNotImplemented = (error) => statusOf(error) === 501 || nameOf(error) === "NotImplemented";
-const isForbidden = (error) => statusOf(error) === 401 || statusOf(error) === 403;
-const isRangeError = (error) => statusOf(error) === 416 || nameOf(error) === "InvalidRange";
-function versionOf(output) {
-  const id = output.VersionId;
-  if (typeof id !== "string" || id === "null" || !VERSION_ID.test(id)) {
-    throw new import_row_storage_errors.ReportingRowStoreError(
-      "UNSAFE_BINDING",
-      "store returned no object VersionId; S3 bucket versioning must be enabled so deletes are fenced to one write"
-    );
-  }
-  return id;
-}
-function selectorOf(nativeVersionRef) {
-  if (typeof nativeVersionRef !== "string" || nativeVersionRef === "null") return null;
-  return VERSION_ID.test(nativeVersionRef) ? { VersionId: nativeVersionRef } : null;
-}
-function servedVersion(output, selector) {
-  return output.VersionId === selector.VersionId;
-}
-function liveExpirationCovers(rule, prefix) {
-  if (rule.Status !== "Enabled") return false;
-  if (rule.Expiration?.Days === void 0 && rule.Expiration?.Date === void 0) return false;
-  if (rule.Filter?.Tag !== void 0 || (rule.Filter?.And?.Tags?.length ?? 0) > 0) return false;
-  const filter = rule.Filter?.Prefix ?? rule.Filter?.And?.Prefix ?? rule.Prefix;
-  return (0, import_row_storage_provider_io.reportingRowPrefixFilterOverlaps)(filter, prefix);
-}
-function createS3ReportingRowObjectProviderV1(options) {
-  if (!options || typeof options !== "object") {
-    throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "S3 row provider options are required");
-  }
-  const clients = (0, import_row_storage_provider_io.reportingRowClientMap)(options.clients);
-  const isClient = (value) => !!value && typeof value === "object" && typeof value.send === "function";
-  if (options.client !== void 0 && !isClient(options.client) || [...clients.values()].some((client) => !isClient(client)) || options.client === void 0 && clients.size === 0) {
-    throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "inject an official S3Client as client or clients");
-  }
-  const validateLocation = (location) => {
-    (0, import_row_storage_provider_io.assertReportingRowLocationKeys)(location, ["bucket"], ["region"]);
-    const bucket = location.bucket;
-    if (!BUCKET.test(bucket) || bucket.includes("..") || /^\d+\.\d+\.\d+\.\d+$/.test(bucket)) {
-      throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "S3 bucket name is invalid");
-    }
-    if (location.region !== void 0 && !REGION.test(location.region)) {
-      throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "S3 region is invalid");
-    }
-  };
-  const target = (input) => {
-    validateLocation(input.location);
-    return {
-      client: (0, import_row_storage_provider_io.selectReportingRowClient)(options.client, clients, input.credentialRef),
-      Bucket: input.location.bucket
-    };
-  };
-  const assertKey = (key) => {
-    if (typeof key !== "string" || key.length === 0 || Buffer.byteLength(key) > 1024) {
-      throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "object key is invalid");
-    }
-  };
-  async function putCreateOnly(client, params, signal) {
-    for (let attempt = 0; ; attempt++) {
-      try {
-        return await client.send(new import_client_s3.PutObjectCommand({ ...params, IfNoneMatch: "*" }), { abortSignal: signal });
-      } catch (error) {
-        if (attempt === 0 && isConditionalConflict(error) && !signal.aborted) continue;
-        throw error;
-      }
-    }
-  }
-  async function assertVersioningEnabled(client, Bucket, signal) {
-    let status;
-    try {
-      status = (await client.send(new import_client_s3.GetBucketVersioningCommand({ Bucket }), { abortSignal: signal })).Status;
-    } catch (error) {
-      if (isForbidden(error) || isNotImplemented(error)) {
-        throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "bucket versioning status cannot be verified");
-      }
-      throw error;
-    }
-    if (status !== "Enabled") {
-      throw new import_row_storage_errors.ReportingRowStoreError(
-        "UNSAFE_BINDING",
-        "S3 bucket versioning must be enabled so row object deletes are fenced to one write"
-      );
-    }
-  }
-  async function assertCreateOnlyEnforced(client, Bucket, prefix, signal) {
-    const Key = `${prefix}/.adcp-probe/${(0, import_node_crypto.randomUUID)()}`;
-    const written = [];
-    const put = async (body) => {
-      const output = await putCreateOnly(
-        client,
-        { Bucket, Key, Body: Buffer.from(body), ContentType: "application/x-ndjson", CacheControl: "no-store" },
-        signal
-      );
-      written.push(output);
-      versionOf(output);
-    };
-    try {
-      try {
-        await put('{"probe":1}\n');
-      } catch (error) {
-        if (isNotImplemented(error) || isPreconditionFailed(error)) {
-          throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "store does not support create-only writes");
-        }
-        throw error;
-      }
-      try {
-        await put('{"probe":2}\n');
-      } catch (error) {
-        if (isPreconditionFailed(error)) return;
-        if (isNotImplemented(error)) {
-          throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "store does not support create-only writes");
-        }
-        throw error;
-      }
-      throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "store ignores If-None-Match and replaces objects");
-    } finally {
-      const versionIds = written.map((output) => output.VersionId).filter((id) => !!id);
-      const deletes = versionIds.length > 0 ? versionIds.map((VersionId) => ({ VersionId })) : written.length ? [{}] : [];
-      for (const selector of deletes) {
-        if (signal.aborted) break;
-        await client.send(new import_client_s3.DeleteObjectCommand({ Bucket, Key, ...selector }), { abortSignal: signal }).catch(() => void 0);
-      }
-    }
-  }
-  return {
-    name: "s3",
-    rangedReads: true,
-    validateLocation,
-    probe(input, context) {
-      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
-        const { client, Bucket } = target(input);
-        const signal = context.signal;
-        try {
-          await client.send(new import_client_s3.HeadBucketCommand({ Bucket }), { abortSignal: signal });
-        } catch (error) {
-          if (isNotFound(error)) throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "bucket does not exist");
-          if (isForbidden(error)) throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "bucket is not accessible");
-          if (statusOf(error) === 301) {
-            throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "bucket is in a different region");
-          }
-          throw error;
-        }
-        if (input.location.region !== void 0) {
-          const configured = client.config?.region;
-          const region = typeof configured === "function" ? await configured() : configured;
-          if (region !== input.location.region) {
-            throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "client region does not match the binding");
-          }
-        }
-        const policy = await client.send(new import_client_s3.GetBucketPolicyStatusCommand({ Bucket }), { abortSignal: signal }).catch(() => void 0);
-        if (policy?.PolicyStatus?.IsPublic === true) {
-          throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "bucket policy makes objects public");
-        }
-        let rules = [];
-        try {
-          const lifecycle = await client.send(new import_client_s3.GetBucketLifecycleConfigurationCommand({ Bucket }), {
-            abortSignal: signal
-          });
-          rules = lifecycle.Rules ?? [];
-        } catch (error) {
-          if (isForbidden(error)) {
-            throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "bucket lifecycle cannot be read with this client");
-          }
-          if (!isNotFound(error) && !isNotImplemented(error) && nameOf(error) !== "NoSuchLifecycleConfiguration") {
-            throw error;
-          }
-        }
-        if (rules.some((rule) => liveExpirationCovers(rule, input.prefix))) {
-          throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "a bucket lifecycle rule can expire live row objects");
-        }
-        await assertVersioningEnabled(client, Bucket, signal);
-        await assertCreateOnlyEnforced(client, Bucket, input.prefix, signal);
-      });
-    },
-    putIfAbsent(input, context) {
-      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
-        const { client, Bucket } = target(input);
-        assertKey(input.objectRef);
-        const bytes = Buffer.from(input.bytes);
-        try {
-          const output = await putCreateOnly(
-            client,
-            {
-              Bucket,
-              Key: input.objectRef,
-              Body: bytes,
-              ContentLength: bytes.byteLength,
-              ContentType: input.contentType,
-              CacheControl: "no-store",
-              Metadata: { ...input.metadata }
-            },
-            context.signal
-          );
-          return { created: true, nativeVersionRef: versionOf(output) };
-        } catch (error) {
-          if (!isPreconditionFailed(error)) throw error;
-        }
-        const head = await client.send(new import_client_s3.HeadObjectCommand({ Bucket, Key: input.objectRef }), {
-          abortSignal: context.signal
-        });
-        return { created: false, nativeVersionRef: versionOf(head) };
-      });
-    },
-    get(input, context) {
-      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
-        const { client, Bucket } = target(input);
-        assertKey(input.objectRef);
-        (0, import_row_storage_provider_io.assertReportingRowReadBounds)(input);
-        const selector = selectorOf(input.nativeVersionRef);
-        if (selector === null) return null;
-        const Key = input.objectRef;
-        try {
-          if (input.range?.length === 0) {
-            const head = await client.send(new import_client_s3.HeadObjectCommand({ Bucket, Key, ...selector }), {
-              abortSignal: context.signal
-            });
-            if (!servedVersion(head, selector)) return null;
-            if (input.range.offset > Number(head.ContentLength ?? 0)) {
-              throw new import_row_storage_errors.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
-            }
-            return Buffer.alloc(0);
-          }
-          const output = await client.send(
-            new import_client_s3.GetObjectCommand({
-              Bucket,
-              Key,
-              ...selector,
-              ...input.range ? { Range: `bytes=${input.range.offset}-${input.range.offset + input.range.length - 1}` } : {}
-            }),
-            { abortSignal: context.signal }
-          );
-          const body = output.Body;
-          if (!body || typeof body[Symbol.asyncIterator] !== "function") {
-            throw new import_row_storage_errors.ReportingRowStoreError("PROVIDER_UNAVAILABLE", "object body is not a stream");
-          }
-          if (!servedVersion(output, selector)) {
-            body.destroy?.();
-            return null;
-          }
-          if (typeof output.ContentLength === "number" && output.ContentLength > input.maxBytes) {
-            body.destroy?.();
-            throw new import_row_storage_errors.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "stored object exceeds its recorded size");
-          }
-          return await (0, import_row_storage_provider_io.readReportingRowStream)(body, input.maxBytes, context.signal);
-        } catch (error) {
-          if (isNotFound(error) || isPreconditionFailed(error)) return null;
-          if (statusOf(error) === 400 && nameOf(error) !== "InvalidRange") return null;
-          if (isRangeError(error)) {
-            throw new import_row_storage_errors.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
-          }
-          throw error;
-        }
-      });
-    },
-    stat(input, context) {
-      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
-        const { client, Bucket } = target(input);
-        assertKey(input.objectRef);
-        const selector = selectorOf(input.nativeVersionRef);
-        if (selector === null) return null;
-        try {
-          const head = await client.send(new import_client_s3.HeadObjectCommand({ Bucket, Key: input.objectRef, ...selector }), {
-            abortSignal: context.signal
-          });
-          if (!servedVersion(head, selector)) return null;
-          const size = head.ContentLength;
-          if (typeof size !== "number" || !Number.isSafeInteger(size) || size < 0) {
-            throw new import_row_storage_errors.ReportingRowStoreError("PROVIDER_UNAVAILABLE", "object metadata is malformed");
-          }
-          return { nativeVersionRef: selector.VersionId, sizeBytes: size };
-        } catch (error) {
-          if (isNotFound(error) || isPreconditionFailed(error)) return null;
-          if (statusOf(error) === 400 || statusOf(error) === 405) return null;
-          throw error;
-        }
-      });
-    },
-    delete(input, context) {
-      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
-        const { client, Bucket } = target(input);
-        assertKey(input.objectRef);
-        const selector = selectorOf(input.nativeVersionRef);
-        if (selector === null) return "absent";
-        const Key = input.objectRef;
-        const signal = context.signal;
-        try {
-          const head = await client.send(new import_client_s3.HeadObjectCommand({ Bucket, Key, ...selector }), { abortSignal: signal });
-          if (!servedVersion(head, selector)) return "absent";
-        } catch (error) {
-          if (isNotFound(error) || isPreconditionFailed(error)) return "absent";
-          if (statusOf(error) === 400 || statusOf(error) === 405) return "absent";
-          throw error;
-        }
-        await client.send(new import_client_s3.DeleteObjectCommand({ Bucket, Key, VersionId: selector.VersionId }), {
-          abortSignal: signal
-        });
-        return "deleted";
-      });
-    }
-  };
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  createS3ReportingRowObjectProviderV1
-});