@davidtnfsh/etl-contracts 1.0.0

package/README.md

@@ -0,0 +1,52 @@
+# @davidtnfsh/etl-contracts
+
+Shared TypeScript and Zod contracts for the All Weather ETL job status system.
+
+## Installation
+
+```bash
+npm install @davidtnfsh/etl-contracts
+```
+
+## Usage
+
+```typescript
+import { EtlJobStatusSchema, type EtlJobStatus } from '@davidtnfsh/etl-contracts';
+
+// Validate API responses
+const response = await fetch('/api/jobs/123');
+const data = await response.json();
+const validated = EtlJobStatusSchema.parse(data);
+
+// TypeScript types
+const job: EtlJobStatus = {
+  jobId: 'etl_123',
+  status: 'completed',
+  trigger: 'webhook',
+  createdAt: '2025-01-07T10:00:00Z',
+  recordsProcessed: 100,
+  recordsInserted: 95
+};
+```
+
+## Schemas
+
+- `EtlJobStatusSchema` - Job status response (flat structure)
+- `EtlJobCreatedSchema` - Job creation response
+- `EtlErrorSchema` - Error structure
+- `JobStatusEnum` - Status values: `pending`, `processing`, `completed`, `failed`
+- `ErrorCodeEnum` - Error codes: `API_ERROR`, `VALIDATION_ERROR`, `INTERNAL_ERROR`, `RATE_LIMIT_EXCEEDED`
+
+## Types
+
+All types are inferred from Zod schemas:
+
+- `EtlJobStatus`
+- `EtlJobCreated`
+- `EtlError`
+- `JobStatus`
+- `ErrorCode`
+
+## License
+
+ISC

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { EtlErrorSchema, EtlJobCreatedSchema, EtlJobStatusSchema, ErrorCodeEnum, JobStatusEnum } from './schemas';
+export type { ErrorCode, EtlError, EtlJobCreated, EtlJobStatus, JobStatus } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,aAAa,EACd,MAAM,WAAW,CAAC;AAGnB,YAAY,EACV,SAAS,EACT,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,SAAS,EACV,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobStatusEnum = exports.ErrorCodeEnum = exports.EtlJobStatusSchema = exports.EtlJobCreatedSchema = exports.EtlErrorSchema = void 0;
+// Export all schemas
+var schemas_1 = require("./schemas");
+Object.defineProperty(exports, "EtlErrorSchema", { enumerable: true, get: function () { return schemas_1.EtlErrorSchema; } });
+Object.defineProperty(exports, "EtlJobCreatedSchema", { enumerable: true, get: function () { return schemas_1.EtlJobCreatedSchema; } });
+Object.defineProperty(exports, "EtlJobStatusSchema", { enumerable: true, get: function () { return schemas_1.EtlJobStatusSchema; } });
+Object.defineProperty(exports, "ErrorCodeEnum", { enumerable: true, get: function () { return schemas_1.ErrorCodeEnum; } });
+Object.defineProperty(exports, "JobStatusEnum", { enumerable: true, get: function () { return schemas_1.JobStatusEnum; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,qBAAqB;AACrB,qCAMmB;AALjB,yGAAA,cAAc,OAAA;AACd,8GAAA,mBAAmB,OAAA;AACnB,6GAAA,kBAAkB,OAAA;AAClB,wGAAA,aAAa,OAAA;AACb,wGAAA,aAAa,OAAA"}

package/dist/schemas.d.ts

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+/**
+ * Job status enum - the source of truth for all status values
+ */
+export declare const JobStatusEnum: z.ZodEnum<["pending", "processing", "completed", "failed"]>;
+/**
+ * Error code enum - simple set for now, extensible
+ */
+export declare const ErrorCodeEnum: z.ZodEnum<["API_ERROR", "VALIDATION_ERROR", "INTERNAL_ERROR", "RATE_LIMIT_EXCEEDED"]>;
+/**
+ * Error structure - simple and clear
+ */
+export declare const EtlErrorSchema: z.ZodObject<{
+    code: z.ZodEnum<["API_ERROR", "VALIDATION_ERROR", "INTERNAL_ERROR", "RATE_LIMIT_EXCEEDED"]>;
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    code: "API_ERROR" | "VALIDATION_ERROR" | "INTERNAL_ERROR" | "RATE_LIMIT_EXCEEDED";
+    message: string;
+}, {
+    code: "API_ERROR" | "VALIDATION_ERROR" | "INTERNAL_ERROR" | "RATE_LIMIT_EXCEEDED";
+    message: string;
+}>;
+/**
+ * Job status response - flat structure, no nesting
+ */
+export declare const EtlJobStatusSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    status: z.ZodEnum<["pending", "processing", "completed", "failed"]>;
+    trigger: z.ZodEnum<["webhook", "manual", "scheduled"]>;
+    createdAt: z.ZodString;
+    recordsProcessed: z.ZodOptional<z.ZodNumber>;
+    recordsInserted: z.ZodOptional<z.ZodNumber>;
+    duration: z.ZodOptional<z.ZodNumber>;
+    completedAt: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodEnum<["API_ERROR", "VALIDATION_ERROR", "INTERNAL_ERROR", "RATE_LIMIT_EXCEEDED"]>;
+        message: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        code: "API_ERROR" | "VALIDATION_ERROR" | "INTERNAL_ERROR" | "RATE_LIMIT_EXCEEDED";
+        message: string;
+    }, {
+        code: "API_ERROR" | "VALIDATION_ERROR" | "INTERNAL_ERROR" | "RATE_LIMIT_EXCEEDED";
+        message: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "processing" | "completed" | "failed";
+    jobId: string;
+    trigger: "webhook" | "manual" | "scheduled";
+    createdAt: string;
+    recordsProcessed?: number | undefined;
+    recordsInserted?: number | undefined;
+    duration?: number | undefined;
+    completedAt?: string | undefined;
+    error?: {
+        code: "API_ERROR" | "VALIDATION_ERROR" | "INTERNAL_ERROR" | "RATE_LIMIT_EXCEEDED";
+        message: string;
+    } | undefined;
+}, {
+    status: "pending" | "processing" | "completed" | "failed";
+    jobId: string;
+    trigger: "webhook" | "manual" | "scheduled";
+    createdAt: string;
+    recordsProcessed?: number | undefined;
+    recordsInserted?: number | undefined;
+    duration?: number | undefined;
+    completedAt?: string | undefined;
+    error?: {
+        code: "API_ERROR" | "VALIDATION_ERROR" | "INTERNAL_ERROR" | "RATE_LIMIT_EXCEEDED";
+        message: string;
+    } | undefined;
+}>;
+/**
+ * Webhook trigger response - returned when creating a job
+ */
+export declare const EtlJobCreatedSchema: z.ZodObject<{
+    jobId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    jobId: string;
+}, {
+    jobId: string;
+}>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,eAAO,MAAM,aAAa,6DAKxB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa,uFAKxB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;EAGzB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAY7B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;EAE9B,CAAC"}

package/dist/schemas.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EtlJobCreatedSchema = exports.EtlJobStatusSchema = exports.EtlErrorSchema = exports.ErrorCodeEnum = exports.JobStatusEnum = void 0;
+const zod_1 = require("zod");
+/**
+ * Job status enum - the source of truth for all status values
+ */
+exports.JobStatusEnum = zod_1.z.enum([
+    'pending',
+    'processing',
+    'completed',
+    'failed'
+]);
+/**
+ * Error code enum - simple set for now, extensible
+ */
+exports.ErrorCodeEnum = zod_1.z.enum([
+    'API_ERROR',
+    'VALIDATION_ERROR',
+    'INTERNAL_ERROR',
+    'RATE_LIMIT_EXCEEDED'
+]);
+/**
+ * Error structure - simple and clear
+ */
+exports.EtlErrorSchema = zod_1.z.object({
+    code: exports.ErrorCodeEnum,
+    message: zod_1.z.string()
+});
+/**
+ * Job status response - flat structure, no nesting
+ */
+exports.EtlJobStatusSchema = zod_1.z.object({
+    jobId: zod_1.z.string(),
+    status: exports.JobStatusEnum,
+    trigger: zod_1.z.enum(['webhook', 'manual', 'scheduled']),
+    createdAt: zod_1.z.string().datetime(), // ISO-8601
+    // Optional fields - only present when relevant
+    recordsProcessed: zod_1.z.number().int().nonnegative().optional(),
+    recordsInserted: zod_1.z.number().int().nonnegative().optional(),
+    duration: zod_1.z.number().int().nonnegative().optional(), // milliseconds
+    completedAt: zod_1.z.string().datetime().optional(), // ISO-8601
+    error: exports.EtlErrorSchema.optional()
+});
+/**
+ * Webhook trigger response - returned when creating a job
+ */
+exports.EtlJobCreatedSchema = zod_1.z.object({
+    jobId: zod_1.z.string()
+});
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAExB;;GAEG;AACU,QAAA,aAAa,GAAG,OAAC,CAAC,IAAI,CAAC;IAClC,SAAS;IACT,YAAY;IACZ,WAAW;IACX,QAAQ;CACT,CAAC,CAAC;AAEH;;GAEG;AACU,QAAA,aAAa,GAAG,OAAC,CAAC,IAAI,CAAC;IAClC,WAAW;IACX,kBAAkB;IAClB,gBAAgB;IAChB,qBAAqB;CACtB,CAAC,CAAC;AAEH;;GAEG;AACU,QAAA,cAAc,GAAG,OAAC,CAAC,MAAM,CAAC;IACrC,IAAI,EAAE,qBAAa;IACnB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE;CACpB,CAAC,CAAC;AAEH;;GAEG;AACU,QAAA,kBAAkB,GAAG,OAAC,CAAC,MAAM,CAAC;IACzC,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;IACjB,MAAM,EAAE,qBAAa;IACrB,OAAO,EAAE,OAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IACnD,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,WAAW;IAE7C,+CAA+C;IAC/C,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IAC3D,eAAe,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IAC1D,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE,EAAE,eAAe;IACpE,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,EAAE,WAAW;IAC1D,KAAK,EAAE,sBAAc,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAEH;;GAEG;AACU,QAAA,mBAAmB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC1C,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;CAClB,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,11 @@
+import type { z } from 'zod';
+import { EtlErrorSchema, EtlJobCreatedSchema, EtlJobStatusSchema, ErrorCodeEnum, JobStatusEnum } from './schemas';
+/**
+ * Inferred TypeScript types from Zod schemas
+ */
+export type JobStatus = z.infer<typeof JobStatusEnum>;
+export type ErrorCode = z.infer<typeof ErrorCodeEnum>;
+export type EtlError = z.infer<typeof EtlErrorSchema>;
+export type EtlJobStatus = z.infer<typeof EtlJobStatusSchema>;
+export type EtlJobCreated = z.infer<typeof EtlJobCreatedSchema>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,aAAa,EACd,MAAM,WAAW,CAAC;AAEnB;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@davidtnfsh/etl-contracts",
+  "version": "1.0.0",
+  "description": "Shared contracts for ETL job status system",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "etl",
+    "contracts",
+    "types"
+  ],
+  "author": "",
+  "license": "ISC",
+  "peerDependencies": {
+    "zod": "^3.0.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "zod": "^3.22.4"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}