@adcp/sdk 14.0.0-beta.27 → 14.0.0-beta.28

package/dist/lib/reporting/inspection.d.ts

@@ -0,0 +1,88 @@
+import { type CanonicalReferenceResolver } from '../canonical-references';
+import { type SsrfFetchOptions } from '../net/ssrf-fetch';
+import type { ReportingControlTotal } from '../types/tools.generated';
+import type { ReportingInspectionContext, ReportingObservation } from './reconciliation';
+export type ReportingInspectionErrorCode = 'UNSUPPORTED_RESOURCE' | 'RESOURCE_READ_FAILED' | 'RESOURCE_NOT_READY' | 'RESOURCE_TOO_LARGE' | 'INSPECTION_TIMEOUT' | 'MANIFEST_DIGEST_MISMATCH' | 'MANIFEST_INVALID' | 'MANIFEST_INCOMPLETE' | 'MANIFEST_IDENTITY_MISMATCH' | 'MANIFEST_TOTAL_MISMATCH' | 'OBJECT_DUPLICATE' | 'OBJECT_SIZE_MISMATCH' | 'OBJECT_DIGEST_MISMATCH' | 'OBJECT_ROW_COUNT_MISMATCH' | 'FORMAT_UNSUPPORTED' | 'COMPRESSION_UNSUPPORTED' | 'ROW_SCHEMA_FETCH_FAILED' | 'ROW_SCHEMA_INVALID' | 'ROW_SCHEMA_VIOLATION' | 'REPORT_DEFINITION_FETCH_FAILED' | 'REPORT_DEFINITION_INVALID' | 'CANONICALIZATION_FETCH_FAILED' | 'CANONICALIZATION_INVALID' | 'ROW_COUNT_MISMATCH' | 'CONTROL_TOTAL_UNSUPPORTED' | 'CONTROL_TOTAL_MISMATCH' | 'CANONICAL_DIGEST_MISMATCH';
+export declare class ReportingInspectionError extends Error {
+    readonly code: ReportingInspectionErrorCode;
+    readonly retryable: boolean;
+    readonly details?: Record<string, unknown> | undefined;
+    readonly observation?: ReportingObservation | undefined;
+    constructor(code: ReportingInspectionErrorCode, message: string, retryable?: boolean, details?: Record<string, unknown> | undefined, options?: ErrorOptions, observation?: ReportingObservation | undefined);
+}
+export type ReportingResourceReadRole = 'manifest' | 'object';
+export interface ReportingResourceReadRequest<TCredential = unknown> {
+    role: ReportingResourceReadRole;
+    location: string;
+    objectRef?: string;
+    expectedSizeBytes?: number;
+    maxBytes: number;
+    credential?: TCredential;
+    context: ReportingInspectionContext;
+    signal?: AbortSignal;
+}
+export interface ReportingResourceReadResult {
+    body: Uint8Array;
+    contentType?: string;
+}
+export interface ReportingResourceReader<TCredential = unknown> {
+    read(request: ReportingResourceReadRequest<TCredential>): Promise<ReportingResourceReadResult>;
+}
+export interface ReportingCredentialProvider<TCredential = unknown> {
+    getCredentials(context: ReportingInspectionContext): Promise<TCredential | undefined>;
+}
+export interface ReportingHttpCredentials {
+    /** Request headers such as Authorization. Values are never copied into errors or receipts. */
+    headers: Readonly<Record<string, string>>;
+    /** Exact HTTPS origins authorized to receive these headers. */
+    allowedOrigins: readonly string[];
+}
+export interface HttpsReportingResourceReaderOptions extends Pick<SsrfFetchOptions, 'allowPrivateIp' | 'timeoutMs' | 'trustedFetchFn' | 'tls'> {
+    maxBodyBytes?: number;
+    /** Exact HTTPS origins authorized to receive configured mTLS material. */
+    tlsAllowedOrigins?: readonly string[];
+}
+/**
+ * Reader for HTTPS manifests and same-origin objects. DNS pinning, private-IP
+ * refusal, redirect blocking, deadlines, and body caps come from ssrfSafeFetch.
+ */
+export declare function createHttpsReportingResourceReader(options?: HttpsReportingResourceReaderOptions): ReportingResourceReader<ReportingHttpCredentials>;
+type ReportingFileFormat = 'jsonl' | 'csv' | 'parquet' | 'avro' | 'orc';
+type ReportingFileCompression = 'none' | 'gzip' | 'zstd' | 'snappy';
+export interface ReportingDecodedFileContext {
+    format: ReportingFileFormat;
+    objectRef: string;
+    rowSchema: Record<string, unknown>;
+    inspection: ReportingInspectionContext;
+    /** Maximum rows this object may return without exceeding the inspection budget. */
+    maxRows: number;
+}
+export type ReportingFormatDecoder = (body: Uint8Array, context: ReportingDecodedFileContext) => Promise<Record<string, unknown>[]> | Record<string, unknown>[];
+export type ReportingCompressionDecoder = (body: Uint8Array, maxOutputBytes: number) => Promise<Uint8Array> | Uint8Array;
+export type ReportingControlTotalCalculator = (rows: readonly Record<string, unknown>[], expected: readonly ReportingControlTotal[], context: ReportingInspectionContext) => Promise<ReportingControlTotal[]> | ReportingControlTotal[];
+export interface ReportingManifestInspectorOptions<TCredential = unknown> {
+    reader: ReportingResourceReader<TCredential>;
+    credentialProvider?: ReportingCredentialProvider<TCredential>;
+    referenceResolver?: CanonicalReferenceResolver;
+    /** Consumer-approved origins for schemas and pinned semantic contracts. */
+    referenceAllowedOrigins: readonly string[];
+    formatDecoders?: Partial<Record<ReportingFileFormat, ReportingFormatDecoder>>;
+    compressionDecoders?: Partial<Record<ReportingFileCompression, ReportingCompressionDecoder>>;
+    controlTotalCalculator?: ReportingControlTotalCalculator;
+    consumerCommitRef?: string | ((context: ReportingInspectionContext) => string | undefined);
+    maxManifestBytes?: number;
+    maxObjectBytes?: number;
+    maxDecodedObjectBytes?: number;
+    maxTotalBytes?: number;
+    maxDecodedTotalBytes?: number;
+    maxFiles?: number;
+    maxRows?: number;
+    maxRowBytes?: number;
+    /** Hard wall-clock budget for one inspection attempt, including custom adapters. */
+    maxInspectionMs?: number;
+    /** Maximum wall-clock time permitted for synchronous row-schema compilation. */
+    maxSchemaCompileMs?: number;
+}
+/** Build the SDK-managed manifest/file inspector used by reconcileReporting. */
+export declare function createReportingManifestInspector<TCredential = unknown>(options: ReportingManifestInspectorOptions<TCredential>): (context: ReportingInspectionContext) => Promise<ReportingObservation>;
+export {};