@convert-buddy/importer-contracts 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,64 @@
+Convert Buddy Free Distribution License 1.0
+
+Copyright (c) Convert Buddy copyright holders. All rights reserved, except as
+expressly granted below or by an applicable separate license.
+
+1. Scope
+This license applies to first-party material in official Convert Buddy package
+distributions carrying this license (the Software), to the extent its copyright
+holders have authority to license that material on these terms. It does not grant
+access to the private development repository or license undistributed source code.
+Previously licensed material and third-party components are addressed in section 5.
+
+2. Free application use
+You may download, install, copy, run, and use the Software without a license fee
+for personal, educational, nonprofit, internal business, and commercial purposes,
+including commercial applications and hosted services. There are no per-user,
+per-record, or revenue limits under this license.
+
+You may bundle and redistribute the Software as part of your applications, SDK
+integrations, websites, and hosted services, including through application stores
+and CDNs. You may modify distributed JavaScript and other distributed integration
+files as needed for those uses, including compilation, bundling, and minification.
+You may mirror unmodified official packages for dependency installation and
+archiving, including private registries and public package caches.
+
+Keep this license and all applicable copyright and third-party notices with
+redistributed copies, or in an accompanying, accessible legal-notices file or page
+when bundling prevents retaining individual files. Identify your modifications
+without implying that the modified distribution is an official Convert Buddy release.
+
+3. Reserved rights
+This is a proprietary distribution license, not an open-source license. Except
+as allowed above, you may not distribute or sublicense the Software as a standalone
+library, engine, or replacement Convert Buddy package, or rebrand or sell it as
+your own standalone software product. This does not restrict selling your own
+applications or services that integrate the Software as permitted in section 2.
+No rights to unpublished source code, trademarks, or an endorsement are granted.
+Rights not expressly granted are reserved. Statutory rights that cannot lawfully
+be excluded or limited by agreement remain unaffected.
+
+4. Hosted services
+This license does not include Convert Buddy Cloud subscriptions, hosted quotas,
+support commitments, or service-level guarantees. Those services have separate
+terms. Their availability or pricing does not change the free-use grant for a
+copy of the Software obtained under this license.
+
+5. Earlier releases and third-party material
+This license does not revoke, replace, or restrict rights already granted under
+MIT or any other separate license. Earlier Convert Buddy releases and portions
+made available under MIT retain those permissions; see NOTICE and accompanying
+license files. Where that material is included in this distribution, its separate
+license continues to apply to that material. Third-party libraries, models,
+datasets, generated bindings, and other separately licensed material retain their
+own terms. These restrictions apply only to first-party material that is not
+already available to you under a broader applicable license. You must comply with
+the applicable notices and licenses for each included component.
+
+6. No warranty or liability
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+NONINFRINGEMENT. TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE COPYRIGHT HOLDERS
+ARE NOT LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF,
+OR IN CONNECTION WITH THE SOFTWARE OR ITS USE, WHETHER IN CONTRACT, TORT, OR
+OTHERWISE.

package/NOTICE

@@ -0,0 +1,33 @@
+Convert Buddy distribution notices
+
+Earlier Convert Buddy releases and portions licensed under MIT retain their
+original permissions. The free distribution license does not revoke those rights.
+The following is the original repository license text, preserved for that material.
+It is not a grant of MIT rights for new proprietary material.
+
+MIT License
+
+Copyright (c) Convert Buddy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Third-party components retain their own licenses and copyright notices. Keep all
+accompanying third-party license files when redistributing. OCR model weights and
+other separately obtained assets require their own license review; this notice
+is not a grant of rights to those assets.

package/README.md

@@ -0,0 +1,74 @@
+# `@convert-buddy/importer-contracts`
+
+Public, versioned data contracts shared by the free importer and Convert
+Buddy Cloud. The package contains plain TypeScript types plus strict runtime
+parsers; persisted configuration is JSON and is not tied to a validation
+framework.
+
+## Contracts
+
+- `TargetSchemaV1` describes an immutable published target schema.
+- `SourceProfileV1` describes a bounded, privacy-reviewed view of an input file.
+- `TransformPlanV1` describes allowlisted deterministic mapping operations.
+- `AcceptedRecordBatchV1` and `DeliveryReceiptV1` define the no-store delivery
+  envelope and acknowledgement.
+
+Every parser rejects unknown properties, oversized payloads, non-JSON values,
+prototype-polluting property names, incompatible operations, and invalid
+cross-contract references. `parseTransformPlanV1` requires the exact source
+profile and target schema version that were used for the mapping request.
+
+```ts
+import {
+  parseSourceProfileV1,
+  parseTargetSchemaV1,
+  parseTransformPlanV1,
+} from "@convert-buddy/importer-contracts";
+
+const schema = parseTargetSchemaV1(schemaJson);
+const profile = parseSourceProfileV1(profileJson);
+const plan = parseTransformPlanV1(modelOutput, {
+  sourceProfile: profile,
+  targetSchema: schema,
+  targetSchemaVersionId: "schema-version-17",
+});
+```
+
+Sample values are rejected by default. A caller must explicitly pass
+`{ allowSamples: true }`, and the configured count and string-length limits are
+still applied.
+
+AI output is always data. This package deliberately has no operation for code,
+general expressions, network access, or dynamic evaluation.
+
+## Delivery verification
+
+Customer endpoints should verify the exact raw request bytes before parsing the
+JSON body. The helper checks HMAC-SHA-256 authenticity and the default five-minute
+freshness window:
+
+```ts
+import {
+  DELIVERY_HEADERS,
+  verifyDeliverySignatureV1,
+} from "@convert-buddy/importer-contracts";
+
+const rawBody = new Uint8Array(await request.arrayBuffer());
+const verified = await verifyDeliverySignatureV1({
+  batchId: request.headers.get(DELIVERY_HEADERS.batchId) ?? "",
+  importId: request.headers.get(DELIVERY_HEADERS.importId) ?? "",
+  rawBody,
+  signature: request.headers.get(DELIVERY_HEADERS.signature) ?? "",
+  signingSecret: env.CONVERT_BUDDY_SIGNING_SECRET,
+  timestamp: request.headers.get(DELIVERY_HEADERS.signatureTimestamp) ?? "",
+});
+```
+
+Make `batchId` idempotent before applying records. Do not reconstruct or
+re-serialize the body for signature verification.
+
+## Distribution and license
+
+Free for personal and commercial application use under the [Convert Buddy Free
+Distribution License](LICENSE). Application bundling is allowed with notices
+retained. Development source is private; Cloud services have separate terms.

package/dist/index.d.ts

@@ -0,0 +1,234 @@
+type JsonPrimitive = null | boolean | number | string;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+declare const TARGET_FIELD_TYPES: readonly ["string", "integer", "number", "boolean", "date", "datetime", "enum"];
+type TargetFieldType = (typeof TARGET_FIELD_TYPES)[number];
+type UnknownFieldPolicyV1 = "ignore" | "reject" | "preserve";
+interface TargetConstraintsV1 {
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    values?: string[];
+}
+interface TargetFieldV1 {
+    key: string;
+    label: string;
+    type: TargetFieldType;
+    required?: boolean;
+    aliases?: string[];
+    description?: string;
+    defaultValue?: JsonValue;
+    constraints?: TargetConstraintsV1;
+}
+interface TargetSchemaV1 {
+    version: 1;
+    id: string;
+    name: string;
+    fields: TargetFieldV1[];
+    unknownFields: UnknownFieldPolicyV1;
+}
+declare const SOURCE_FORMATS: readonly ["csv", "xml", "json", "ndjson", "xlsx"];
+type SourceFormatV1 = (typeof SOURCE_FORMATS)[number];
+declare const SOURCE_INFERRED_TYPES: readonly ["string", "integer", "number", "boolean", "date", "datetime", "enum", "null", "object", "array", "unknown"];
+type SourceInferredTypeV1 = (typeof SOURCE_INFERRED_TYPES)[number];
+interface SourceInferredTypeRatioV1 {
+    type: SourceInferredTypeV1;
+    ratio: number;
+}
+interface SourceFieldProfileV1 {
+    path: string;
+    normalizedName: string;
+    inferredTypes: SourceInferredTypeRatioV1[];
+    nullRatio: number;
+    distinctEstimate?: number;
+    samples?: string[];
+}
+interface SourceProfileV1 {
+    version: 1;
+    format: SourceFormatV1;
+    structureFingerprint: string;
+    recordPath?: string;
+    fields: SourceFieldProfileV1[];
+}
+type TransformOperationV1 = {
+    op: "trim";
+} | {
+    op: "lowercase";
+} | {
+    op: "uppercase";
+} | {
+    op: "coerce";
+    type: Exclude<TargetFieldType, "enum">;
+} | {
+    op: "parse_date";
+    formats: string[];
+} | {
+    op: "replace";
+    pattern: string;
+    replacement: string;
+} | {
+    op: "enum_map";
+    values: Record<string, string>;
+} | {
+    op: "split";
+    separator: string;
+    index: number;
+} | {
+    op: "join";
+    separator: string;
+} | {
+    op: "default";
+    value: JsonValue;
+};
+interface TransformMappingV1 {
+    sources: string[];
+    target: string;
+    confidence: number;
+    reasonCode: string;
+    operations: TransformOperationV1[];
+}
+interface TransformWarningV1 {
+    code: string;
+    message: string;
+}
+interface TransformPlanV1 {
+    version: 1;
+    sourceFingerprint: string;
+    targetSchemaVersionId: string;
+    mappings: TransformMappingV1[];
+    unmappedSources: string[];
+    unsatisfiedTargets: string[];
+    warnings: TransformWarningV1[];
+}
+interface AcceptedRecordBatchV1 {
+    version: 1;
+    records: Array<Record<string, JsonValue>>;
+}
+interface DeliveryReceiptV1 {
+    version: 1;
+    batchId: string;
+    recordCount: number;
+    status: "delivered" | "duplicate";
+}
+type ContractIssueCode = "invalid_type" | "invalid_value" | "missing_value" | "unknown_property" | "duplicate_value" | "limit_exceeded" | "unsafe_pattern" | "incompatible_operation" | "unknown_source" | "unknown_target" | "fingerprint_mismatch" | "schema_version_mismatch";
+interface ContractIssue {
+    code: ContractIssueCode;
+    path: string;
+    message: string;
+}
+
+declare function canonicalStringify(value: unknown): string;
+declare function canonicalByteLength(value: unknown): number;
+declare function cloneJsonValue(value: JsonValue): JsonValue;
+
+/** Calendar dates are never interpreted in the browser's local timezone. */
+declare function isCalendarDate(value: string): boolean;
+/** Datetimes require an explicit UTC offset; ambiguous local times are rejected. */
+declare function isOffsetDateTime(value: string): boolean;
+/** Explicit numeric calendar formats; conflicting interpretations remain invalid. */
+declare function parseCalendarFormats(value: string, formats: readonly string[]): string | undefined;
+
+interface ContractLimits {
+    maxAliasesPerField: number;
+    maxCanonicalBytes: number;
+    maxDescriptionLength: number;
+    maxDictionaryEntries: number;
+    maxFields: number;
+    maxMappings: number;
+    maxOperationsPerMapping: number;
+    maxPatternLength: number;
+    maxRecordPathLength: number;
+    maxSamplesPerField: number;
+    maxSampleLength: number;
+    maxStringLength: number;
+    maxWarnings: number;
+}
+declare const DEFAULT_CONTRACT_LIMITS: Readonly<ContractLimits>;
+interface ContractParseOptions {
+    allowSamples?: boolean;
+    limits?: Partial<ContractLimits>;
+}
+declare function resolveContractLimits(overrides: Partial<ContractLimits> | undefined): Readonly<ContractLimits>;
+
+declare const DELIVERY_PROTOCOL_VERSION: 1;
+declare const DEFAULT_MAX_DELIVERY_BATCH_BYTES: number;
+declare const DEFAULT_MAX_DELIVERY_BATCH_RECORDS = 10000;
+declare const DEFAULT_DELIVERY_SIGNATURE_TOLERANCE_SECONDS: number;
+declare const DELIVERY_HEADERS: Readonly<{
+    readonly apiKey: "x-convert-buddy-key";
+    readonly batchId: "x-convert-buddy-batch-id";
+    readonly destination: "x-convert-buddy-destination";
+    readonly importId: "x-convert-buddy-import-id";
+    readonly signature: "x-convert-buddy-signature";
+    readonly signatureTimestamp: "x-convert-buddy-signature-timestamp";
+}>;
+interface DeliveryBatchParseOptions extends ContractParseOptions {
+    maxBatchBytes?: number;
+    maxRecords?: number;
+}
+interface DeliverySignatureInputV1 {
+    batchId: string;
+    importId: string;
+    rawBody: Uint8Array;
+    timestamp: string;
+}
+interface DeliverySignatureVerificationV1 extends DeliverySignatureInputV1 {
+    nowEpochSeconds?: number;
+    signature: string;
+    signingSecret: string | Uint8Array;
+    toleranceSeconds?: number;
+}
+declare function parseAcceptedRecordBatchV1(input: unknown, options?: DeliveryBatchParseOptions): AcceptedRecordBatchV1;
+declare function signDeliveryRequestV1(signingSecret: string | Uint8Array, input: DeliverySignatureInputV1): Promise<string>;
+declare function verifyDeliverySignatureV1(input: DeliverySignatureVerificationV1): Promise<boolean>;
+
+interface StructureDescriptorV1 {
+    version: 1;
+    format: SourceProfileV1["format"];
+    recordPath?: string;
+    fields: Array<{
+        path: string;
+        normalizedName: string;
+        inferredTypes: string[];
+    }>;
+}
+declare function describeSourceStructure(profile: SourceProfileV1): StructureDescriptorV1;
+declare function computeStructureFingerprint(profile: SourceProfileV1): Promise<string>;
+
+declare function parseSourceProfileV1(input: unknown, options?: ContractParseOptions): SourceProfileV1;
+
+declare function parseTargetSchemaV1(input: unknown, options?: ContractParseOptions): TargetSchemaV1;
+declare function isTargetValueCompatible(value: JsonValue, type: TargetFieldType): boolean;
+
+interface TargetSchemaBuilderOptionsV1 {
+    id: string;
+    name: string;
+    unknownFields?: UnknownFieldPolicyV1;
+}
+/** Creates validated, immutable schema manifests without coupling consumers to a validator library. */
+declare class TargetSchemaBuilderV1 {
+    #private;
+    private readonly options;
+    constructor(options: Readonly<TargetSchemaBuilderOptionsV1>);
+    field(field: Readonly<TargetFieldV1>): this;
+    fields(fields: ReadonlyArray<Readonly<TargetFieldV1>>): this;
+    build(): Readonly<TargetSchemaV1>;
+}
+declare function defineTargetSchemaV1(schema: Readonly<TargetSchemaV1>): Readonly<TargetSchemaV1>;
+
+interface TransformPlanContextV1 {
+    sourceProfile: SourceProfileV1;
+    targetSchema: TargetSchemaV1;
+    targetSchemaVersionId: string;
+}
+declare function parseTransformPlanV1(input: unknown, planContext: TransformPlanContextV1, options?: ContractParseOptions): TransformPlanV1;
+
+declare class ContractValidationError extends TypeError {
+    readonly issues: readonly ContractIssue[];
+    constructor(contractName: string, issues: readonly ContractIssue[]);
+}
+
+export { type AcceptedRecordBatchV1, type ContractIssue, type ContractIssueCode, type ContractLimits, type ContractParseOptions, ContractValidationError, DEFAULT_CONTRACT_LIMITS, DEFAULT_DELIVERY_SIGNATURE_TOLERANCE_SECONDS, DEFAULT_MAX_DELIVERY_BATCH_BYTES, DEFAULT_MAX_DELIVERY_BATCH_RECORDS, DELIVERY_HEADERS, DELIVERY_PROTOCOL_VERSION, type DeliveryBatchParseOptions, type DeliveryReceiptV1, type DeliverySignatureInputV1, type DeliverySignatureVerificationV1, type JsonPrimitive, type JsonValue, SOURCE_FORMATS, SOURCE_INFERRED_TYPES, type SourceFieldProfileV1, type SourceFormatV1, type SourceInferredTypeRatioV1, type SourceInferredTypeV1, type SourceProfileV1, TARGET_FIELD_TYPES, type TargetConstraintsV1, type TargetFieldType, type TargetFieldV1, type TargetSchemaBuilderOptionsV1, TargetSchemaBuilderV1, type TargetSchemaV1, type TransformMappingV1, type TransformOperationV1, type TransformPlanContextV1, type TransformPlanV1, type TransformWarningV1, type UnknownFieldPolicyV1, canonicalByteLength, canonicalStringify, cloneJsonValue, computeStructureFingerprint, defineTargetSchemaV1, describeSourceStructure, isCalendarDate, isOffsetDateTime, isTargetValueCompatible, parseAcceptedRecordBatchV1, parseCalendarFormats, parseSourceProfileV1, parseTargetSchemaV1, parseTransformPlanV1, resolveContractLimits, signDeliveryRequestV1, verifyDeliverySignatureV1 };