feat(client): async import-job methods on both data namespaces

Add createImportJob / getImportJobProgress / getImportJobResults /
listImportJobs / cancelImportJob to the top-level and scoped `data`
namespaces, mirroring the async REST routes. Large payloads are posted once
via createImportJob (returns a jobId immediately); callers poll progress /
results / history and can cancel. Older servers return 404 → rejected promise,
so consumers can feature-detect and fall back to the synchronous `import`.

5 client tests assert route/method/query-string shaping and response
unwrapping.

Author: baozhoutao

packages/client/src/client.test.ts

@@ -1051,3 +1051,51 @@ describe('ObjectStackClient locale → Accept-Language', () => {
         expect(lastHeaders(fetchMock)['Accept-Language']).toBeUndefined();
     });
 });
+
+describe('Import-job namespace', () => {
+    it('createImportJob POSTs the payload to /data/:object/import/jobs', async () => {
+        const { client, fetchMock } = createMockClient({ jobId: 'imp_x', object: 'task', status: 'pending', total: 3, createdAt: '2026-07-01T00:00:00Z' });
+        const res = await client.data.createImportJob('task', { format: 'json', rows: [{ id: 'a' }] } as any);
+        const [url, init] = fetchMock.mock.calls[0];
+        expect(url).toBe('http://localhost:3000/api/v1/data/task/import/jobs');
+        expect(init.method).toBe('POST');
+        expect(res).toMatchObject({ jobId: 'imp_x', status: 'pending', total: 3 });
+    });
+
+    it('getImportJobProgress GETs /data/import/jobs/:jobId', async () => {
+        const { client, fetchMock } = createMockClient({ jobId: 'imp_x', object: 'task', status: 'running', percentComplete: 40 });
+        const res = await client.data.getImportJobProgress('imp_x');
+        expect(fetchMock.mock.calls[0][0]).toBe('http://localhost:3000/api/v1/data/import/jobs/imp_x');
+        expect(res.percentComplete).toBe(40);
+    });
+
+    it('getImportJobResults GETs the /results sub-route', async () => {
+        const { client, fetchMock } = createMockClient({ jobId: 'imp_x', status: 'succeeded', results: [{ row: 1, ok: true, action: 'created' }], resultsTruncated: false });
+        const res = await client.data.getImportJobResults('imp_x');
+        expect(fetchMock.mock.calls[0][0]).toBe('http://localhost:3000/api/v1/data/import/jobs/imp_x/results');
+        expect(res.results).toHaveLength(1);
+        expect(res.resultsTruncated).toBe(false);
+    });
+
+    it('listImportJobs builds the query string and unwraps the jobs array', async () => {
+        const { client, fetchMock } = createMockClient({ jobs: [{ jobId: 'imp_x', object: 'task', status: 'succeeded' }] });
+        const jobs = await client.data.listImportJobs({ object: 'task', status: 'succeeded', limit: 10, offset: 5 });
+        const url = fetchMock.mock.calls[0][0] as string;
+        expect(url.startsWith('http://localhost:3000/api/v1/data/import/jobs?')).toBe(true);
+        expect(url).toContain('object=task');
+        expect(url).toContain('status=succeeded');
+        expect(url).toContain('limit=10');
+        expect(url).toContain('offset=5');
+        expect(jobs).toHaveLength(1);
+        expect(jobs[0].jobId).toBe('imp_x');
+    });
+
+    it('cancelImportJob POSTs the /cancel sub-route', async () => {
+        const { client, fetchMock } = createMockClient({ success: true });
+        const res = await client.data.cancelImportJob('imp_x');
+        const [url, init] = fetchMock.mock.calls[0];
+        expect(url).toBe('http://localhost:3000/api/v1/data/import/jobs/imp_x/cancel');
+        expect(init.method).toBe('POST');
+        expect(res.success).toBe(true);
+    });
+});

packages/client/src/index.ts

@@ -84,6 +84,13 @@ import {
   ApiRoutes,
   ImportRequest,
   ImportResponse,
+  CreateImportJobRequest,
+  CreateImportJobResponse,
+  ImportJobProgress,
+  ImportJobResults,
+  ImportJobSummary,
+  ListImportJobsRequest,
+  ListImportJobsResponse,
 } from '@objectstack/spec/api';
 import type {
   ApprovalRequestRow,
@@ -3067,6 +3074,62 @@ export class ObjectStackClient {
         return this.unwrapResponse<ImportResponse>(res);
     },
 
+    /**
+     * Import-job namespace — the asynchronous counterpart to {@link import} for
+     * large files (up to 50,000 rows). `createImportJob` posts the whole payload
+     * once and returns immediately with a `jobId`; a server worker processes the
+     * batch in the background. Poll {@link getImportJobProgress} for live
+     * counters, {@link getImportJobResults} for the capped per-row report, and
+     * {@link listImportJobs} for history. {@link cancelImportJob} stops a
+     * pending/running job cooperatively.
+     *
+     * These routes require a server new enough to expose them — older servers
+     * return 404, which surfaces here as a rejected promise. Callers that want
+     * graceful degradation should feature-detect (e.g. try the job, fall back
+     * to the synchronous {@link import} on 404).
+     */
+    createImportJob: async (object: string, request: CreateImportJobRequest): Promise<CreateImportJobResponse> => {
+        const route = this.getRoute('data');
+        const res = await this.fetch(`${this.baseUrl}${route}/${object}/import/jobs`, {
+            method: 'POST',
+            body: JSON.stringify(request),
+        });
+        return this.unwrapResponse<CreateImportJobResponse>(res);
+    },
+
+    getImportJobProgress: async (jobId: string): Promise<ImportJobProgress> => {
+        const route = this.getRoute('data');
+        const res = await this.fetch(`${this.baseUrl}${route}/import/jobs/${encodeURIComponent(jobId)}`);
+        return this.unwrapResponse<ImportJobProgress>(res);
+    },
+
+    getImportJobResults: async (jobId: string): Promise<ImportJobResults> => {
+        const route = this.getRoute('data');
+        const res = await this.fetch(`${this.baseUrl}${route}/import/jobs/${encodeURIComponent(jobId)}/results`);
+        return this.unwrapResponse<ImportJobResults>(res);
+    },
+
+    listImportJobs: async (query: Partial<ListImportJobsRequest> = {}): Promise<ImportJobSummary[]> => {
+        const route = this.getRoute('data');
+        const qs = new URLSearchParams();
+        if (query.object) qs.set('object', query.object);
+        if (query.status) qs.set('status', query.status);
+        if (query.limit != null) qs.set('limit', String(query.limit));
+        if (query.offset != null) qs.set('offset', String(query.offset));
+        const suffix = qs.toString() ? `?${qs.toString()}` : '';
+        const res = await this.fetch(`${this.baseUrl}${route}/import/jobs${suffix}`);
+        const body = await this.unwrapResponse<ListImportJobsResponse>(res);
+        return body.jobs;
+    },
+
+    cancelImportJob: async (jobId: string): Promise<{ success: boolean }> => {
+        const route = this.getRoute('data');
+        const res = await this.fetch(`${this.baseUrl}${route}/import/jobs/${encodeURIComponent(jobId)}/cancel`, {
+            method: 'POST',
+        });
+        return this.unwrapResponse<{ success: boolean }>(res);
+    },
+
     update: async <T = any>(
         object: string,
         id: string,
@@ -3492,6 +3555,43 @@ export class ScopedProjectClient {
       });
       return this.parent._unwrap<ImportResponse>(res);
     },
+    /**
+     * Asynchronous import jobs (scoped) — see the top-level `data.createImportJob`
+     * for semantics. Large payloads are posted once; a server worker processes
+     * them in the background while callers poll progress / results / history.
+     */
+    createImportJob: async (object: string, request: CreateImportJobRequest): Promise<CreateImportJobResponse> => {
+      const res = await this.parent._fetch(this.url(`/data/${object}/import/jobs`), {
+        method: 'POST',
+        body: JSON.stringify(request),
+      });
+      return this.parent._unwrap<CreateImportJobResponse>(res);
+    },
+    getImportJobProgress: async (jobId: string): Promise<ImportJobProgress> => {
+      const res = await this.parent._fetch(this.url(`/data/import/jobs/${encodeURIComponent(jobId)}`));
+      return this.parent._unwrap<ImportJobProgress>(res);
+    },
+    getImportJobResults: async (jobId: string): Promise<ImportJobResults> => {
+      const res = await this.parent._fetch(this.url(`/data/import/jobs/${encodeURIComponent(jobId)}/results`));
+      return this.parent._unwrap<ImportJobResults>(res);
+    },
+    listImportJobs: async (query: Partial<ListImportJobsRequest> = {}): Promise<ImportJobSummary[]> => {
+      const qs = new URLSearchParams();
+      if (query.object) qs.set('object', query.object);
+      if (query.status) qs.set('status', query.status);
+      if (query.limit != null) qs.set('limit', String(query.limit));
+      if (query.offset != null) qs.set('offset', String(query.offset));
+      const suffix = qs.toString() ? `?${qs.toString()}` : '';
+      const res = await this.parent._fetch(this.url(`/data/import/jobs${suffix}`));
+      const body = await this.parent._unwrap<ListImportJobsResponse>(res);
+      return body.jobs;
+    },
+    cancelImportJob: async (jobId: string): Promise<{ success: boolean }> => {
+      const res = await this.parent._fetch(this.url(`/data/import/jobs/${encodeURIComponent(jobId)}/cancel`), {
+        method: 'POST',
+      });
+      return this.parent._unwrap<{ success: boolean }>(res);
+    },
     update: async <T = any>(object: string, id: string, data: Partial<T>): Promise<UpdateDataResult<T>> => {
       const res = await this.parent._fetch(this.url(`/data/${object}/${id}`), {
         method: 'PATCH',
@@ -3674,6 +3774,13 @@ export type {
   AuthProviderInfo,
   EmailPasswordConfigPublic,
   AuthFeaturesConfig,
+  CreateImportJobRequest,
+  CreateImportJobResponse,
+  ImportJobProgress,
+  ImportJobResults,
+  ImportJobSummary,
+  ListImportJobsRequest,
+  ListImportJobsResponse,
 } from '@objectstack/spec/api';
 
 // Approval runtime types (ADR-0019) — surfaced so SDK consumers can type the