@datashift/sdk 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Datashift, Inc.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,411 @@
1
+ # @datashift/sdk
2
+
3
+ TypeScript SDK for integrating human-in-the-loop checkpoints into AI agent workflows.
4
+
5
+ ## Overview
6
+
7
+ Datashift enables AI agents to submit tasks for human review before committing changes. Perfect for data enrichment workflows where AI agents enhance CRM and database records with external data, and reviewers verify accuracy before updates are applied.
8
+
9
+ ## Installation
10
+
11
+ ```bash
12
+ npm install @datashift/sdk
13
+ ```
14
+
15
+ ## Quick Start
16
+
17
+ ```typescript
18
+ import {DatashiftRestClient} from '@datashift/sdk';
19
+
20
+ const datashift = new DatashiftRestClient({
21
+ apiKey: process.env.DATASHIFT_API_KEY!,
22
+ });
23
+
24
+ // AI agent enriches company data from external sources
25
+ const enrichedData = {
26
+ companyId: 'acme_corp_123',
27
+ original: {name: 'Acme Corp', industry: 'Unknown'},
28
+ enriched: {
29
+ name: 'Acme Corporation',
30
+ industry: 'Manufacturing',
31
+ employees: 5200,
32
+ revenue: '$1.2B',
33
+ linkedIn: 'https://linkedin.com/company/acme',
34
+ },
35
+ sources: ['LinkedIn', 'Crunchbase', 'SEC Filings'],
36
+ };
37
+
38
+ // Submit enrichment for human verification before updating CRM
39
+ const task = await datashift.task.submit({
40
+ queueKey: 'data-enrichment',
41
+ data: enrichedData,
42
+ summary: 'Verify Acme Corp enrichment before CRM update',
43
+ });
44
+
45
+ // Wait for reviewer approval
46
+ const result = await datashift.task.waitForReview(task.id, {
47
+ timeout: 300000, // 5 minutes
48
+ pollInterval: 5000, // Check every 5 seconds
49
+ });
50
+
51
+ // Apply verified changes to CRM
52
+ if (result.result.includes('approved')) {
53
+ await updateCRM(enrichedData.companyId, enrichedData.enriched);
54
+ }
55
+ ```
56
+
57
+ ## Authentication
58
+
59
+ Create an API key in the Datashift Console.
60
+
61
+ ```typescript
62
+ const datashift = new DatashiftRestClient({
63
+ apiKey: 'sk_live_...', // Production key
64
+ // apiKey: 'sk_test_...', // Test key
65
+ });
66
+ ```
67
+
68
+ ## REST Client API
69
+
70
+ ### Task Operations
71
+
72
+ ```typescript
73
+ // Submit a task
74
+ const task = await datashift.task.submit({
75
+ queueKey: 'approvals',
76
+ data: {...},
77
+ summary: 'Short description',
78
+ });
79
+
80
+ // Get task by ID
81
+ const task = await datashift.task.get(taskId);
82
+
83
+ // Get task status (lightweight)
84
+ const status = await datashift.task.getStatus(taskId);
85
+
86
+ // List tasks
87
+ const tasks = await datashift.task.list({
88
+ queueId?: string;
89
+ state?: 'pending' | 'queued' | 'completed';
90
+ });
91
+
92
+ // Wait for review
93
+ const completed = await datashift.task.waitForReview(taskId, {
94
+ timeout: 300000, // 5 minutes
95
+ pollInterval: 2000, // Start at 2s
96
+ maxPollInterval: 30000 // Back off to 30s
97
+ });
98
+ ```
99
+
100
+ ### Queue Operations
101
+
102
+ ```typescript
103
+ // List queues
104
+ const queues = await datashift.queue.list();
105
+
106
+ // Get queue config
107
+ const queue = await datashift.queue.get('refund-approvals');
108
+ ```
109
+
110
+ ### Review Operations
111
+
112
+ ```typescript
113
+ // List reviews with filters
114
+ const reviews = await datashift.review.list({
115
+ queueKey: 'approvals',
116
+ reviewerType: 'human',
117
+ from: new Date('2024-01-01'),
118
+ limit: 50,
119
+ });
120
+
121
+ // Get review by ID
122
+ const review = await datashift.review.get(reviewId);
123
+ ```
124
+
125
+ ### Webhook Operations
126
+
127
+ ```typescript
128
+ // Create webhook
129
+ const webhook = await datashift.webhook.create({
130
+ url: 'https://your-service.com/webhook',
131
+ events: ['task.completed'],
132
+ });
133
+ // Save webhook.secret securely!
134
+
135
+ // List webhooks
136
+ const webhooks = await datashift.webhook.list();
137
+
138
+ // Update webhook
139
+ const updated = await datashift.webhook.update(webhookId, {
140
+ url: 'https://new-url.com/webhook',
141
+ events: ['task.completed', 'task.created'],
142
+ active: true,
143
+ });
144
+
145
+ // Rotate webhook secret
146
+ const rotated = await datashift.webhook.rotateSecret(webhookId);
147
+ // Save rotated.secret securely!
148
+
149
+ // Send test event
150
+ await datashift.webhook.test(webhookId);
151
+
152
+ // Delete webhook
153
+ await datashift.webhook.delete(webhookId);
154
+ ```
155
+
156
+ ## Webhooks
157
+
158
+ Webhooks provide async notifications when tasks are completed.
159
+
160
+ ### Setting Up a Webhook Endpoint
161
+
162
+ ```typescript
163
+ import express from 'express';
164
+ import {verifyWebhookSignature, parseWebhookEvent} from '@datashift/sdk';
165
+ import type {WebhookEvent} from '@datashift/sdk';
166
+
167
+ const app = express();
168
+
169
+ // IMPORTANT: Use raw body for signature verification
170
+ app.post('/webhook/datashift',
171
+ express.raw({type: 'application/json'}),
172
+ (req, res) => {
173
+ const signature = req.headers['x-datashift-signature'] as string;
174
+
175
+ // Verify signature
176
+ if (!verifyWebhookSignature(req.body, signature, WEBHOOK_SECRET)) {
177
+ return res.status(401).send('Invalid signature');
178
+ }
179
+
180
+ // Parse event
181
+ const event = parseWebhookEvent<WebhookEvent>(req.body);
182
+
183
+ if (event.event === 'task.completed') {
184
+ const {task_id, result, review} = event.data;
185
+ handleTaskCompleted(task_id, result, review);
186
+ }
187
+
188
+ res.status(200).send('OK');
189
+ }
190
+ );
191
+ ```
192
+
193
+ ### Webhook Events
194
+
195
+ | Event | Description |
196
+ |------------------|--------------------------------|
197
+ | `task.completed` | Task review has been completed |
198
+
199
+ ### Webhook Payload
200
+
201
+ ```typescript
202
+ interface WebhookEvent {
203
+ event: string; // Event type
204
+ timestamp: string; // ISO 8601 timestamp
205
+ data: {
206
+ task_id: string;
207
+ queue_key: string;
208
+ state: string;
209
+ result: string[];
210
+ review?: Review;
211
+ };
212
+ }
213
+ ```
214
+
215
+ ## Types
216
+
217
+ ### Task
218
+
219
+ ```typescript
220
+ interface Task {
221
+ id: string;
222
+ queue_id: string;
223
+ external_id: string | null;
224
+ state: 'pending' | 'queued' | 'completed';
225
+ data: Record<string, unknown>;
226
+ context: Record<string, unknown>;
227
+ metadata: Record<string, unknown>;
228
+ summary: string | null;
229
+ sla_deadline: string | null;
230
+ completed_at: string | null;
231
+ created_at: string;
232
+ updated_at: string;
233
+ reviews?: Review[];
234
+ }
235
+ ```
236
+
237
+ ### Queue
238
+
239
+ ```typescript
240
+ interface Queue {
241
+ id: string;
242
+ key: string;
243
+ name: string;
244
+ description: string | null;
245
+ review_type: 'approval' | 'labeling' | 'classification' | 'scoring' | 'augmentation';
246
+ review_options: ReviewOption[];
247
+ assignment: 'manual' | 'round_robin' | 'ai_first';
248
+ sla_minutes: number | null;
249
+ deleted_at: string | null;
250
+ }
251
+ ```
252
+
253
+ ### Review
254
+
255
+ ```typescript
256
+ interface Review {
257
+ id: string;
258
+ task_id: string;
259
+ reviewer_id: string | null;
260
+ result: string[];
261
+ data: Record<string, unknown>;
262
+ comment: string | null;
263
+ created_at: string;
264
+ }
265
+ ```
266
+
267
+ ### ListReviewsFilters
268
+
269
+ ```typescript
270
+ interface ListReviewsFilters {
271
+ taskId?: string;
272
+ reviewerId?: string;
273
+ queueKey?: string;
274
+ reviewerType?: 'ai' | 'human';
275
+ from?: Date | string;
276
+ to?: Date | string;
277
+ limit?: number;
278
+ offset?: number;
279
+ }
280
+ ```
281
+
282
+ ### ReviewResult
283
+
284
+ ```typescript
285
+ interface ReviewResult {
286
+ task_id: string;
287
+ result: string[];
288
+ data: Record<string, unknown>;
289
+ completed_at: string;
290
+ review: Review;
291
+ }
292
+ ```
293
+
294
+ ## Error Handling
295
+
296
+ The SDK provides typed error classes for common error scenarios.
297
+
298
+ ```typescript
299
+ import {
300
+ DatashiftError,
301
+ AuthenticationError,
302
+ NotFoundError,
303
+ ValidationError,
304
+ TimeoutError,
305
+ RateLimitError,
306
+ ServerError,
307
+ } from '@datashift/sdk';
308
+
309
+ try {
310
+ const result = await datashift.task.waitForReview(taskId, {timeout: 60000});
311
+ } catch (error) {
312
+ if (error instanceof TimeoutError) {
313
+ console.log('Review not completed in time');
314
+ } else if (error instanceof AuthenticationError) {
315
+ console.log('Invalid credentials');
316
+ } else if (error instanceof NotFoundError) {
317
+ console.log('Task not found');
318
+ } else if (error instanceof RateLimitError) {
319
+ console.log(`Rate limited. Retry after ${error.retryAfter}s`);
320
+ } else if (error instanceof DatashiftError) {
321
+ console.log(`API error: ${error.message}`);
322
+ }
323
+ }
324
+ ```
325
+
326
+ ## Configuration
327
+
328
+ ### REST Client Options
329
+
330
+ ```typescript
331
+ interface RestClientConfig {
332
+ apiKey: string; // Required
333
+ baseUrl?: string; // Default: 'https://api.datashift.io'
334
+ timeout?: number; // Request timeout (default: 30000ms)
335
+ retries?: number; // Retry count (default: 3)
336
+ retryDelay?: number; // Initial retry delay (default: 1000ms)
337
+ }
338
+ ```
339
+
340
+ ### Wait Options
341
+
342
+ ```typescript
343
+ interface WaitOptions {
344
+ timeout?: number; // Max wait time (default: 300000ms)
345
+ pollInterval?: number; // Poll interval (default: 2000ms)
346
+ maxPollInterval?: number; // Max poll interval for backoff (default: 30000ms)
347
+ }
348
+ ```
349
+
350
+ ## Examples
351
+
352
+ ### Backend Service with Webhooks
353
+
354
+ ```typescript
355
+ import {DatashiftRestClient, verifyWebhookSignature, parseWebhookEvent} from '@datashift/sdk';
356
+ import type {WebhookEvent} from '@datashift/sdk';
357
+ import express from 'express';
358
+
359
+ const datashift = new DatashiftRestClient({
360
+ apiKey: process.env.DATASHIFT_API_KEY!,
361
+ });
362
+
363
+ // Store pending tasks (use Redis/DB in production)
364
+ const pendingTasks = new Map<string, (result: any) => void>();
365
+
366
+ // Submit task and return immediately
367
+ async function submitForReview(data: any): Promise<string> {
368
+ const task = await datashift.task.submit({
369
+ queueKey: 'reviews',
370
+ data,
371
+ });
372
+ return task.id;
373
+ }
374
+
375
+ // Webhook handler
376
+ const app = express();
377
+
378
+ app.post('/webhook/datashift',
379
+ express.raw({type: 'application/json'}),
380
+ (req, res) => {
381
+ const signature = req.headers['x-datashift-signature'] as string;
382
+
383
+ if (!verifyWebhookSignature(req.body, signature, process.env.WEBHOOK_SECRET!)) {
384
+ return res.status(401).send('Invalid signature');
385
+ }
386
+
387
+ const event = parseWebhookEvent<WebhookEvent>(req.body);
388
+
389
+ if (event.event === 'task.completed') {
390
+ const resolver = pendingTasks.get(event.data.task_id);
391
+ if (resolver) {
392
+ resolver(event.data);
393
+ pendingTasks.delete(event.data.task_id);
394
+ }
395
+ }
396
+
397
+ res.status(200).send('OK');
398
+ }
399
+ );
400
+
401
+ app.listen(3000);
402
+ ```
403
+
404
+ ## Requirements
405
+
406
+ - Node.js 18+
407
+ - TypeScript 5.0+ (for type definitions)
408
+
409
+ ## License
410
+
411
+ MIT
@@ -0,0 +1,232 @@
1
+ import { AxiosInstance } from 'axios';
2
+
3
+ type TaskState = 'pending' | 'queued' | 'completed';
4
+ interface Task {
5
+ id: string;
6
+ organization_id: string;
7
+ queue_id: string;
8
+ external_id: string | null;
9
+ state: TaskState;
10
+ data: Record<string, unknown>;
11
+ context: Record<string, unknown>;
12
+ metadata: Record<string, unknown>;
13
+ summary: string | null;
14
+ sla_deadline: string | null;
15
+ completed_at: string | null;
16
+ created_at: string;
17
+ updated_at: string;
18
+ queue?: Queue;
19
+ reviews?: Review[];
20
+ }
21
+ interface TaskStatus {
22
+ state: TaskState;
23
+ completed_at: string | null;
24
+ }
25
+ interface SubmitTaskInput {
26
+ queueKey: string;
27
+ data: Record<string, unknown>;
28
+ context?: Record<string, unknown>;
29
+ metadata?: Record<string, unknown>;
30
+ summary?: string;
31
+ externalId?: string;
32
+ }
33
+ type ReviewType = 'approval' | 'labeling' | 'classification' | 'scoring' | 'augmentation';
34
+ type AssignmentStrategy = 'manual' | 'round_robin' | 'ai_first' | 'ai_last';
35
+ interface ReviewOption {
36
+ id: string;
37
+ label: string;
38
+ display_order: number;
39
+ }
40
+ interface Queue {
41
+ id: string;
42
+ organization_id: string;
43
+ key: string;
44
+ name: string;
45
+ description: string | null;
46
+ review_type: ReviewType;
47
+ review_options: ReviewOption[];
48
+ multi_select: boolean;
49
+ assignment: AssignmentStrategy;
50
+ sla_minutes: number | null;
51
+ deleted_at: string | null;
52
+ created_at: string;
53
+ updated_at: string;
54
+ }
55
+ interface Review {
56
+ id: string;
57
+ task_id: string;
58
+ queue_id: string | null;
59
+ reviewer_id: string | null;
60
+ result: string[];
61
+ data: Record<string, unknown>;
62
+ comment: string | null;
63
+ created_at: string;
64
+ }
65
+ interface ListReviewsFilters {
66
+ taskId?: string;
67
+ reviewerId?: string;
68
+ queueKey?: string;
69
+ reviewerType?: 'ai' | 'human';
70
+ from?: Date | string;
71
+ to?: Date | string;
72
+ limit?: number;
73
+ offset?: number;
74
+ }
75
+ interface RestClientConfig {
76
+ apiKey: string;
77
+ baseUrl?: string;
78
+ timeout?: number;
79
+ retries?: number;
80
+ retryDelay?: number;
81
+ }
82
+ interface WaitOptions {
83
+ timeout?: number;
84
+ pollInterval?: number;
85
+ maxPollInterval?: number;
86
+ }
87
+ interface ReviewResult {
88
+ task_id: string;
89
+ result: string[];
90
+ data: Record<string, unknown>;
91
+ completed_at: string;
92
+ review: Review;
93
+ }
94
+
95
+ declare class TaskResource {
96
+ private client;
97
+ constructor(client: AxiosInstance);
98
+ /**
99
+ * Submit a task for human review
100
+ */
101
+ submit(input: SubmitTaskInput): Promise<Task>;
102
+ /**
103
+ * Get a task by ID with full details
104
+ */
105
+ get(taskId: string): Promise<Task>;
106
+ /**
107
+ * Get task status
108
+ */
109
+ getStatus(taskId: string): Promise<TaskStatus>;
110
+ /**
111
+ * List tasks with optional filters
112
+ */
113
+ list(filters?: {
114
+ queueId?: string;
115
+ state?: string;
116
+ }): Promise<Task[]>;
117
+ /**
118
+ * Wait for a task to be reviewed
119
+ */
120
+ waitForReview(taskId: string, options?: WaitOptions): Promise<Task>;
121
+ private sleep;
122
+ }
123
+
124
+ declare class QueueResource {
125
+ private client;
126
+ constructor(client: AxiosInstance);
127
+ /**
128
+ * List all queues available to the organization
129
+ */
130
+ list(): Promise<Queue[]>;
131
+ /**
132
+ * Get a queue by key
133
+ */
134
+ get(key: string): Promise<Queue>;
135
+ }
136
+
137
+ declare class ReviewResource {
138
+ private client;
139
+ constructor(client: AxiosInstance);
140
+ /**
141
+ * List reviews with optional filters
142
+ */
143
+ list(filters?: ListReviewsFilters): Promise<Review[]>;
144
+ /**
145
+ * Get a review by ID
146
+ */
147
+ get(reviewId: string): Promise<Review>;
148
+ }
149
+
150
+ /**
151
+ * Datashift REST API client
152
+ *
153
+ * Use this client for backend service integrations with API key authentication.
154
+ * For AI agents with real-time push notifications, use DatashiftMcpClient instead.
155
+ *
156
+ * @example
157
+ * ```typescript
158
+ * const datashift = new DatashiftRestClient({
159
+ * apiKey: 'sk_live_...',
160
+ * });
161
+ *
162
+ * const task = await datashift.task.submit({
163
+ * queueKey: 'approvals',
164
+ * data: { action: 'delete-account' },
165
+ * });
166
+ *
167
+ * const result = await datashift.task.waitForReview(task.id);
168
+ * ```
169
+ */
170
+ declare class DatashiftRestClient {
171
+ private client;
172
+ private retries;
173
+ private retryDelay;
174
+ readonly task: TaskResource;
175
+ readonly queue: QueueResource;
176
+ readonly review: ReviewResource;
177
+ constructor(config: RestClientConfig);
178
+ private setupErrorInterceptor;
179
+ private shouldRetry;
180
+ private transformError;
181
+ private sleep;
182
+ }
183
+
184
+ /**
185
+ * Base error class for all Datashift SDK errors
186
+ */
187
+ declare class DatashiftError extends Error {
188
+ status?: number | undefined;
189
+ code?: string | undefined;
190
+ data?: unknown | undefined;
191
+ constructor(message: string, status?: number | undefined, code?: string | undefined, data?: unknown | undefined);
192
+ }
193
+ /**
194
+ * Thrown when authentication fails (invalid API key, expired token, etc.)
195
+ */
196
+ declare class AuthenticationError extends DatashiftError {
197
+ constructor(message?: string);
198
+ }
199
+ /**
200
+ * Thrown when a requested resource is not found
201
+ */
202
+ declare class NotFoundError extends DatashiftError {
203
+ constructor(resource: string, id?: string);
204
+ }
205
+ /**
206
+ * Thrown when request validation fails
207
+ */
208
+ declare class ValidationError extends DatashiftError {
209
+ errors?: Record<string, string[]> | undefined;
210
+ constructor(message: string, errors?: Record<string, string[]> | undefined);
211
+ }
212
+ /**
213
+ * Thrown when an operation times out
214
+ */
215
+ declare class TimeoutError extends DatashiftError {
216
+ constructor(message?: string);
217
+ }
218
+ /**
219
+ * Thrown when rate limited
220
+ */
221
+ declare class RateLimitError extends DatashiftError {
222
+ retryAfter?: number | undefined;
223
+ constructor(retryAfter?: number | undefined);
224
+ }
225
+ /**
226
+ * Thrown when the server returns an error
227
+ */
228
+ declare class ServerError extends DatashiftError {
229
+ constructor(message?: string);
230
+ }
231
+
232
+ export { type AssignmentStrategy, AuthenticationError, DatashiftError, DatashiftRestClient, type ListReviewsFilters, NotFoundError, type Queue, RateLimitError, type RestClientConfig, type Review, type ReviewOption, type ReviewResult, type ReviewType, ServerError, type SubmitTaskInput, type Task, type TaskState, type TaskStatus, TimeoutError, ValidationError, type WaitOptions };