SDK

@wport/sdk

@wport/sdk 是 W101 Talent Search Hub 公開 API 的官方 TypeScript／JavaScript SDK，提供與 @wport/cli 相同的能力，作為型別化函式庫給你自己的程式使用。公開職缺搜尋免憑證；企業招募操作用你的 wpk_live_ API key。

狀態：0.x —— 公開 jobs.* 與企業 jobs.* 線。求職者的 personal.* 線尚未啟用，呼叫會 throw PersonalNotEnabledError。

安裝

bash
npm install @wport/sdk

Node ≥ 18.17，隨附 ESM + CJS + 型別宣告。

Quickstart

免憑證：公開職缺搜尋 / 檢視。

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);

企業：把 API key 傳進建構子（SDK 只認建構子注入）。

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 選項

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

可依賴的行為

  • 認證僅由建構子注入。未帶 key → 企業方法在送出任何請求前就 throw AuthRequiredError。
  • Idempotency：企業寫入自動帶 Idempotency-Key（後端要求）。
  • 型別化錯誤（全部繼承 WportError）；SDK 不設 process exit code —— 那是 CLI 的事。
  • Batch 走 server 端 batch endpoint（每次 1–10 筆），無法超過 server 上限。
  • 每個請求標記 X-Source: typescript_sdk 供稽核。

型別化錯誤

類別說明
WportError所有 SDK 錯誤的基底類別
WportHttpErrorHTTP 非 2xx；帶 status 與 body
WportNetworkError連線 / 逾時等網路層錯誤
AuthRequiredError未帶 key 就呼叫企業方法（送出請求前即 throw）
PersonalNotEnabledErrorpersonal.* 尚未啟用時呼叫會 throw

Exports

WportClient、WportClientOptions、上述錯誤類別，以及結果／查詢型別：

WportClientWportClientOptionsWportErrorWportHttpErrorWportNetworkErrorAuthRequiredErrorPersonalNotEnabledErrorJobSearchItemJobViewSearchQueryPaginatedBodyCreatedJobEnterpriseJobItemEnterpriseJobsListQueryEnterpriseJobUpdateOptionsBatchResult

下一步