SDK

@wport/sdk

@wport/sdk is the official TypeScript/JavaScript SDK for the W101 Talent Search Hub public API — the same capabilities as @wport/cli, as a typed library for your own code. Public job search needs no credentials; enterprise operations use your wpk_live_ API key.

Status: 0.x — public jobs.* and enterprise jobs.* lines. The job-seeker personal.* line is not enabled yet and throws PersonalNotEnabledError.

Install

bash
npm install @wport/sdk

Node >= 18.17. Ships ESM + CJS + type declarations.

Quickstart

Keyless: public job search / view.

ts
import { WportClient } from '@wport/sdk';

// Keyless：公開職缺搜尋 / 檢視
const wport = new WportClient();
const page = await wport.jobs.search({ keyword: 'backend' });
const job = await wport.jobs.view(page.data[0].enc_id);

Enterprise: pass your API key into the constructor (constructor injection only).

ts
import { WportClient } from '@wport/sdk';

// Enterprise：建構子注入 API key（SDK 不自行讀 config / env）
const ent = new WportClient({ apiKey: process.env.WPORT_API_KEY });
const created = await ent.enterprise.jobs.create({ title: '...' });
await ent.enterprise.jobs.update(created.enc_id, { title: '...' }, { ifMatch: '...' });

// batch = { succeeded: [{index, enc_id}], failed: [{index, error_path}] }
// 部分成功會回傳，不會 throw
const batch = await ent.enterprise.jobs.bulkCreate([{ title: 'a' }, { title: 'b' }]);

WportClient options

ts
new WportClient({
  apiKey?: string,    // 企業線；純公開用途可省略
  apiBase?: string,   // 預設 https://api.wport.me
  locale?: string,    // 預設 zh-TW
  timeoutMs?: number, // 預設 30000
});

Behavior you can rely on

  • Auth is constructor-injected only. No key → enterprise methods throw AuthRequiredError before any request.
  • Idempotency: enterprise writes send an auto-generated Idempotency-Key (required by the backend).
  • Typed errors (all extend WportError); no process exit codes — that is CLI territory.
  • Batch goes through the server-side batch endpoint (1–10 jobs per call); it cannot fan out past server limits.
  • Every request is tagged X-Source: typescript_sdk for audit.

Typed errors

ClassDescription
WportErrorBase class for all SDK errors
WportHttpErrorNon-2xx HTTP; carries status and body
WportNetworkErrorNetwork-layer errors (connection / timeout)
AuthRequiredErrorEnterprise method called without a key (thrown before any request)
PersonalNotEnabledErrorThrown when personal.* is called (not enabled yet)

Exports

WportClient, WportClientOptions, the error classes above, and result/query types:

WportClientWportClientOptionsWportErrorWportHttpErrorWportNetworkErrorAuthRequiredErrorPersonalNotEnabledErrorJobSearchItemJobViewSearchQueryPaginatedBodyCreatedJobEnterpriseJobItemEnterpriseJobsListQueryEnterpriseJobUpdateOptionsBatchResult

Next