@joymerrevent/porters-connect 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-07-01
+
+### Added
+
+- **一括書き込み**（F-4 / ADR-0041・`CLAUDE.md`）。各データ系リソースに **`createMany`** / **`updateMany`** を追加。
+  - `porters.candidate.createMany([...])` / `updateMany([{ id, fields }, ...])` で複数レコードをまとめて書き込み。
+  - **1 リクエスト最大 200 件＋約 15000 文字**に自動分割（バッチを逐次送信）。1 件で上限超過は送信前に `PortersConfigError`。
+  - **非アトミック**: 戻り値 **`BulkWriteResult`**（`results`＝送信順の per-item `{ index, id, code, ok }`／`failed`／`hasFailures`）で
+    部分成功を返します（per-item の失敗は throw しません）。リクエスト全体の失敗のみ throw（バッチ途中の失敗は既書き込み件数を hint に付与）。
+  - `createMany` はバッチ跨ぎで**非冪等**（全体の再実行は作成を重複させ得る）。Attachment は対象外（単件のみ）。
+  - 新規 export 型 `BulkWriteResult` / `BulkWriteResultItem`。
+
+## [0.5.0] - 2026-06-29
+
+### Added
+
+- **マルチテナント面**（F-3 / ADR-0040・ADR-0008/0021）。`porters.tenant(id)` で partition（Company DB）を
+  束ねたアクセサ群 `TenantScope` を返します。`porters.tenant(123).candidate.search(...)` は `partition=123`
+  を毎回付与し、未束ねの呼び出しは **client 既定 `partition`** を使います（解決は tenant スコープ／client 既定の 2 層）。
+  - スコープは data（candidate/job/client/process/resume）＋ attachment ＋ master Read（user/field/option）を露出。
+    `auth`（App 単位）・`partition` マスタ（発見専用・partition 非送信）・`tenant`（ネスト不可）は含みません。
+  - partition 別トークンが必要な場合は**テナント別 `PortersClient`** を構築（ADR-0008 案3）。
+  - 新規 export 型 `TenantScope`。`PortersClientOptions.partition` の JSDoc を更新（per-call 引数は設けない方針）。
+
 ## [0.4.0] - 2026-06-27
 
 ### Added
@@ -100,7 +124,9 @@
 [oauth-guide]: docs/guide/oauth.md
 [kac]: https://keepachangelog.com/en/1.1.0/
 [semver]: https://semver.org/
-[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.4.0...HEAD
+[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/Joymerrevent/porters-connect/compare/v0.2.0...v0.2.1

package/README.md

@@ -56,9 +56,13 @@ const porters = new PortersClient({
   host: process.env.PORTERS_HOST!, // 契約時に通知される値。ハードコード禁止
   appId: process.env.PORTERS_APP_ID!,
   appSecret: process.env.PORTERS_APP_SECRET!,
-  partition: 123, // Partition（Company DB）Id
+  partition: 123, // 既定 Partition（Company DB）Id
 });
 
+// 複数 partition を 1 つの App で扱う SaaS は porters.tenant(id) で束ねる
+const t = porters.tenant(456);
+await t.candidate.search({ condition: { P_Name: { part: "鈴木" } } }); // partition=456
+
 // 検索（最大 200 件/ページ）。condition は項目の Data Type ごとに型付き
 const page = await porters.candidate.search({
   condition: { P_Name: { part: "山田" } }, // テキストは part（部分一致）/ full（完全一致）
@@ -79,6 +83,8 @@ for await (const c of porters.candidate.searchAll({
 }
 ```
 
+> 複数 partition を 1 つの App で扱う（マルチテナント SaaS）場合の `porters.tenant(id)` スコープ・テナント別 client・partition 発見は [マルチテナント ガイド][multi-tenancy] にまとめています。
+>
 > 認証情報やホスト名は**コミットしない**でください。`.env.example` を参考に `.env` で渡します。
 
 ## 契約なしで試す（オフライン評価）
@@ -275,9 +281,16 @@ await porters.process.create({
   P_Candidate: 10001,
   P_Resume: 50,
 });
+
+// 一括作成／更新（200 件＋サイズで自動分割・部分成功を返す）
+const bulk = await porters.candidate.createMany([
+  { P_Owner: 5, P_Name: "山田 太郎" },
+  { P_Owner: 5, P_Name: "鈴木 花子" },
+]);
+if (bulk.hasFailures) console.warn(bulk.failed); // per-item は throw せず結果で返す
 ```
 
-> 1 リクエストの長さは**約 15000 文字**まで（PORTERS 仕様）。超えるとライブラリが送信前に弾きます。
+> 1 リクエストの長さは**約 15000 文字**まで（PORTERS 仕様）。超えるとライブラリが送信前に弾きます。一括書き込み（`createMany` / `updateMany`）は 200 件＋サイズで自動分割し、部分成功を `BulkWriteResult` で返します — 詳しくは [一括書き込み ガイド][bulk-write] を参照。
 
 ## 添付ファイル（Attachment）
 
@@ -365,6 +378,8 @@ try {
 [auth-flow]: ./docs/reference/authentication-api/README.md
 [oauth-guide]: ./docs/guide/oauth.md
 [error-handling]: ./docs/guide/error-handling.md
+[multi-tenancy]: ./docs/guide/multi-tenancy.md
+[bulk-write]: ./docs/guide/bulk-write.md
 [sandbox]: ./examples/offline-sandbox.ts
 [adr]: ./docs/adr/README.md
 [design]: ./docs/design/basic-design.md

package/dist/index.d.ts

@@ -252,6 +252,28 @@ type SearchQuery<F extends FieldCatalog = FieldCatalog> = {
     start?: number;
 };
 
+/** One record's outcome from a bulk write, in the position it was sent (ADR-0041 SD-2). */
+type BulkWriteResultItem = {
+    /** 0-based index in the input array. */
+    index: number;
+    /** Assigned (create) / echoed (update) record id. Meaningful only when `ok`. */
+    id: number;
+    /** PORTERS per-item Result Code (`0` = success). */
+    code: number;
+    /** `code === 0`. */
+    ok: boolean;
+};
+/**
+ * The result of `createMany` / `updateMany` (ADR-0041). `results` holds every record's outcome in
+ * input order; `failed` is the `ok === false` subset. A per-item `code !== 0` does **not** throw —
+ * a bulk write mixes successes and failures — so always inspect `hasFailures` / `failed`.
+ */
+type BulkWriteResult = {
+    results: BulkWriteResultItem[];
+    failed: BulkWriteResultItem[];
+    hasFailures: boolean;
+};
+
 type WritableKeys<F extends FieldCatalog> = {
     [K in keyof F]: F[K] extends WritableDataType ? K : never;
 }[keyof F];
@@ -277,6 +299,22 @@ type Resource<F extends FieldCatalog, Req extends keyof F> = {
     create(input: CreateInput<F, Req>): Promise<number>;
     /** Update one record by id; resolves to that id. */
     update(id: number, input: UpdateInput<F>): Promise<number>;
+    /**
+     * Create many records in one call (ADR-0041 / F-4). Auto-batched to ≤200 records and under the
+     * request size cap. **Not atomic** — inspect the {@link BulkWriteResult}: per-record failures are
+     * returned (`failed` / `hasFailures`), not thrown. Only a whole-request failure throws (with the
+     * already-written count). Batching is non-idempotent: a full retry after a mid-run failure may
+     * duplicate creates. Empty input sends no request.
+     */
+    createMany(inputs: CreateInput<F, Req>[]): Promise<BulkWriteResult>;
+    /**
+     * Update many records by id in one call (ADR-0041 / F-4). Auto-batched like {@link createMany};
+     * per-record failures are returned in the {@link BulkWriteResult}, not thrown.
+     */
+    updateMany(items: {
+        id: number;
+        fields: UpdateInput<F>;
+    }[]): Promise<BulkWriteResult>;
 };
 
 declare const FIELDS$8: {
@@ -714,7 +752,11 @@ type PortersClientOptions<C extends DeclaredCatalogs = EmptyCatalog> = {
     appId?: string;
     appSecret?: string;
     scopes?: Scope[];
-    /** Partition (Company DB) used for every call. Per-call override is not yet supported (planned — see ADR-0033). */
+    /**
+     * Default partition (Company DB) for every call. For multi-tenant routing, bind a partition
+     * per call with {@link PortersClient.tenant} (ADR-0040 / F-3); for a fully separated per-partition
+     * token, construct a dedicated client per tenant instead (ADR-0008 案3).
+     */
     partition?: PartitionId;
     /** Custom auth strategy; defaults to the transparent code_direct strategy. */
     auth?: TokenProvider;
@@ -729,6 +771,22 @@ type PortersClientOptions<C extends DeclaredCatalogs = EmptyCatalog> = {
      */
     fields?: DefinedFields<C>;
 };
+/**
+ * The partition-bound resource accessors returned by {@link PortersClient.tenant} (ADR-0040 / F-3).
+ * Every accessor here routes to the bound tenant's partition. `auth` (App-level), the `partition`
+ * master (discovery — partition-less), and `tenant` itself (no nesting) are deliberately absent.
+ */
+type TenantScope<C extends DeclaredCatalogs = EmptyCatalog> = {
+    readonly candidate: CandidateResource<CustomFor<C, "candidate">>;
+    readonly job: JobResource<CustomFor<C, "job">>;
+    readonly client: ClientResource<CustomFor<C, "client">>;
+    readonly process: ProcessResource<CustomFor<C, "process">>;
+    readonly resume: ResumeResource<CustomFor<C, "resume">>;
+    readonly attachment: AttachmentResource;
+    readonly user: UserResource;
+    readonly field: FieldResource;
+    readonly option: OptionResource;
+};
 /**
  * Entry point of the library. Wires the default transport / auth / throttle /
  * requester and exposes namespaced resource accessors such as `candidate`
@@ -752,6 +810,16 @@ declare class PortersClient<C extends DeclaredCatalogs = EmptyCatalog> {
     readonly field: FieldResource;
     /** Master Read: a tenant's choice (option) master (ADR-0021/0022). */
     readonly option: OptionResource;
+    /**
+     * Bind a tenant's partition (Company DB) once and route every call through it — the multi-tenant
+     * scope (ADR-0008 案2 / renamed in ADR-0021 / implemented in ADR-0040 F-3).
+     * `porters.tenant(123).candidate.search(...)` sends `partition=123` without repeating it, overriding
+     * the client-default `partition`. Returns the partition-bound accessors (data + attachment + master
+     * User/Field/Option); `auth` (App-level), the `partition` master (discovery — takes no partition),
+     * and `tenant` itself (no nesting) are intentionally omitted. For a fully separated per-partition
+     * token, construct a dedicated {@link PortersClient} per tenant instead (ADR-0008 案3).
+     */
+    readonly tenant: (id: PartitionId) => TenantScope<C>;
     constructor(options: PortersClientOptions<C>);
     /** The configured API host. */
     get host(): string;
@@ -805,4 +873,4 @@ declare const bytesToBase64: (bytes: Uint8Array) => string;
 /** Decode a Base64 string back to raw bytes. */
 declare const base64ToBytes: (b64: string) => Uint8Array;
 
-export { type Attachment, type AttachmentCreate, type AttachmentPage, type AttachmentResource, type AttachmentSearchQuery, type AttachmentUpdate, type AuthApi, type AuthorizationUrlOptions, type Candidate, type CandidateCreateInput, type CandidatePage, type CandidateResource, type CandidateSearchQuery, type CandidateUpdateInput, type Client, type ClientCreateInput, type ClientPage, type ClientResource, type ClientSearchQuery, type ClientUpdateInput, type Condition, type CustomDataType, type DefinedFields, type ErrorCategory, type Field, type FieldBuilder, type FieldDecls, type FieldDef, type FieldPage, type FieldResource, type FieldSearchQuery, type FieldValue, type GetAccessTokenOptions, type ItemState, type Job, type JobCreateInput, type JobPage, type JobResource, type JobSearchQuery, type JobUpdateInput, type MockHandler, type MockReply, type MockTransportOptions, type Option, type OptionResource, type OptionSearchQuery, type Order, type Partition, type PartitionId, type PartitionPage, type PartitionResource, type PartitionSearchQuery, PortersAuthError, PortersClient, type PortersClientOptions, PortersConfigError, PortersError, type PortersErrorContext, type PortersErrorOptions, PortersNetworkError, PortersResourceError, type Process, type ProcessCreateInput, type ProcessPage, type ProcessResource, type ProcessSearchQuery, type ProcessUpdateInput, type ResourceType, type Resume, type ResumeCreateInput, type ResumePage, type ResumeResource, type ResumeSearchQuery, type ResumeUpdateInput, type RevokeUrlOptions, type Scope, type SearchQuery, type StoredTokens, type TokenProvider, type TokenStore, type Transport, type TransportRequest, type TransportResponse, type User, type UserPage, type UserRef, type UserResource, type UserSearchQuery, base64ToBytes, bytesToBase64, createMockTransport, defineFields };
+export { type Attachment, type AttachmentCreate, type AttachmentPage, type AttachmentResource, type AttachmentSearchQuery, type AttachmentUpdate, type AuthApi, type AuthorizationUrlOptions, type BulkWriteResult, type BulkWriteResultItem, type Candidate, type CandidateCreateInput, type CandidatePage, type CandidateResource, type CandidateSearchQuery, type CandidateUpdateInput, type Client, type ClientCreateInput, type ClientPage, type ClientResource, type ClientSearchQuery, type ClientUpdateInput, type Condition, type CustomDataType, type DefinedFields, type ErrorCategory, type Field, type FieldBuilder, type FieldDecls, type FieldDef, type FieldPage, type FieldResource, type FieldSearchQuery, type FieldValue, type GetAccessTokenOptions, type ItemState, type Job, type JobCreateInput, type JobPage, type JobResource, type JobSearchQuery, type JobUpdateInput, type MockHandler, type MockReply, type MockTransportOptions, type Option, type OptionResource, type OptionSearchQuery, type Order, type Partition, type PartitionId, type PartitionPage, type PartitionResource, type PartitionSearchQuery, PortersAuthError, PortersClient, type PortersClientOptions, PortersConfigError, PortersError, type PortersErrorContext, type PortersErrorOptions, PortersNetworkError, PortersResourceError, type Process, type ProcessCreateInput, type ProcessPage, type ProcessResource, type ProcessSearchQuery, type ProcessUpdateInput, type ResourceType, type Resume, type ResumeCreateInput, type ResumePage, type ResumeResource, type ResumeSearchQuery, type ResumeUpdateInput, type RevokeUrlOptions, type Scope, type SearchQuery, type StoredTokens, type TenantScope, type TokenProvider, type TokenStore, type Transport, type TransportRequest, type TransportResponse, type User, type UserPage, type UserRef, type UserResource, type UserSearchQuery, base64ToBytes, bytesToBase64, createMockTransport, defineFields };

package/dist/index.js

@@ -590,10 +590,9 @@ var encodeItem = (prefix, fields, item) => {
   }
   return parts.join("");
 };
+var encodeWriteItem = (prefix, fields, item) => `<Item>${encodeItem(prefix, fields, item)}</Item>`;
 var buildWriteXml = (config) => {
-  const items = config.items.map(
-    (item) => `<Item>${encodeItem(config.prefix, config.fields, item)}</Item>`
-  ).join("");
+  const items = config.items.map((item) => encodeWriteItem(config.prefix, config.fields, item)).join("");
   return `<${config.resource}>${items}</${config.resource}>`;
 };
 
@@ -780,6 +779,87 @@ var appendReadQuery = (p, q, ctx) => {
   }
 };
 
+// src/resources/bulk-write.ts
+var MAX_ITEMS_PER_REQUEST = 200;
+var packBatches = (encoded, budget) => {
+  const batches = [];
+  let batch = [];
+  let length = 0;
+  for (const e of encoded) {
+    if (e.xml.length > budget) {
+      throw new PortersConfigError(
+        `a single record serializes to ${e.xml.length} characters, over the ~${budget}-character budget for one request`,
+        {
+          category: "config",
+          hint: "Reduce that record's field values \u2014 a bulk request (URL + body) is capped at ~15000 characters."
+        }
+      );
+    }
+    if (batch.length >= MAX_ITEMS_PER_REQUEST || length + e.xml.length > budget) {
+      batches.push(batch);
+      batch = [];
+      length = 0;
+    }
+    batch.push(e);
+    length += e.xml.length;
+  }
+  if (batch.length > 0) batches.push(batch);
+  return batches;
+};
+var batchFailure = (cause, written, resource, partition) => {
+  const base = cause instanceof PortersError ? cause : void 0;
+  return new PortersResourceError(
+    `bulk write failed after ${written} record(s) had already been written`,
+    {
+      category: base?.category ?? "unknown",
+      code: base?.code ?? null,
+      retryable: false,
+      httpStatus: base?.httpStatus,
+      hint: `${written} record(s) from earlier batches were already written; retry only the records from index ${written} onward (create is non-idempotent \u2014 a full retry would duplicate them).`,
+      context: { resource, operation: "bulkWrite", partition },
+      cause
+    }
+  );
+};
+var runBulkWrite = async (requester, target, items, idempotent) => {
+  const envelope = `<${target.name}></${target.name}>`.length;
+  const budget = MAX_REQUEST_LENGTH - target.url.length - envelope;
+  const encoded = items.map((item, index) => ({
+    index,
+    xml: encodeWriteItem(target.prefix, target.fields, item)
+  }));
+  const batches = packBatches(encoded, budget);
+  const results = [];
+  let written = 0;
+  for (const batch of batches) {
+    const body = `<${target.name}>${batch.map((e) => e.xml).join("")}</${target.name}>`;
+    let parsed;
+    try {
+      parsed = await requester.request(
+        { method: "POST", url: target.url, headers: {}, body },
+        parseWriteResult,
+        { write: true, idempotent }
+      );
+    } catch (cause) {
+      if (written === 0) throw cause;
+      throw batchFailure(cause, written, target.name, target.partition);
+    }
+    if (parsed.length !== batch.length) {
+      throw new PortersResourceError(
+        `bulk write response returned ${parsed.length} result(s) for ${batch.length} record(s)`,
+        { category: "unknown", context: { resource: target.name } }
+      );
+    }
+    batch.forEach((e, i) => {
+      const { id, code } = parsed[i];
+      results.push({ index: e.index, id, code, ok: code === 0 });
+    });
+    written += batch.length;
+  }
+  const failed = results.filter((r) => !r.ok);
+  return { results, failed, hasFailures: failed.length > 0 };
+};
+
 // src/resources/resource.ts
 var USER_SUBFIELDS = ["P_Id", "P_Type", "P_Name", "P_Mail"];
 var defaultFieldList = (prefix, fields) => Object.entries(fields).map(
@@ -851,7 +931,25 @@ var createResource = (config, deps) => {
   );
   const create = (input) => write({ ...input, P_Id: -1 }, false);
   const update = (id, input) => write({ ...input, P_Id: id }, true);
-  return { search, searchAll, get, create, update };
+  const target = {
+    name: config.name,
+    prefix: config.prefix,
+    fields: fieldMap,
+    partition: deps.partition
+  };
+  const createMany = (inputs) => runBulkWrite(
+    deps.requester,
+    { ...target, url: writeUrl() },
+    inputs.map((input) => ({ ...input, P_Id: -1 })),
+    false
+  );
+  const updateMany = (items) => runBulkWrite(
+    deps.requester,
+    { ...target, url: writeUrl() },
+    items.map(({ id, fields }) => ({ ...fields, P_Id: id })),
+    true
+  );
+  return { search, searchAll, get, create, update, createMany, updateMany };
 };
 
 // src/resources/candidate.ts
@@ -1339,6 +1437,16 @@ var PortersClient = class {
   field;
   /** Master Read: a tenant's choice (option) master (ADR-0021/0022). */
   option;
+  /**
+   * Bind a tenant's partition (Company DB) once and route every call through it — the multi-tenant
+   * scope (ADR-0008 案2 / renamed in ADR-0021 / implemented in ADR-0040 F-3).
+   * `porters.tenant(123).candidate.search(...)` sends `partition=123` without repeating it, overriding
+   * the client-default `partition`. Returns the partition-bound accessors (data + attachment + master
+   * User/Field/Option); `auth` (App-level), the `partition` master (discovery — takes no partition),
+   * and `tenant` itself (no nesting) are intentionally omitted. For a fully separated per-partition
+   * token, construct a dedicated {@link PortersClient} per tenant instead (ADR-0008 案3).
+   */
+  tenant;
   #host;
   constructor(options) {
     const transport = options.transport ?? createFetchTransport();
@@ -1373,22 +1481,33 @@ var PortersClient = class {
       backoff: expoBackoff()
     });
     this.#host = options.host;
-    const deps = {
-      requester,
-      host: options.host,
-      partition: options.partition ?? 0
-    };
     const customFor = (key) => options.fields?.[key] ?? {};
-    this.candidate = createCandidateResource(deps, customFor("candidate"));
-    this.job = createJobResource(deps, customFor("job"));
-    this.client = createClientResource(deps, customFor("client"));
-    this.process = createProcessResource(deps, customFor("process"));
-    this.resume = createResumeResource(deps, customFor("resume"));
-    this.attachment = createAttachmentResource(deps);
+    const buildScope = (partition) => {
+      const deps = { requester, host: options.host, partition };
+      return {
+        candidate: createCandidateResource(deps, customFor("candidate")),
+        job: createJobResource(deps, customFor("job")),
+        client: createClientResource(deps, customFor("client")),
+        process: createProcessResource(deps, customFor("process")),
+        resume: createResumeResource(deps, customFor("resume")),
+        attachment: createAttachmentResource(deps),
+        user: createUserResource(deps),
+        field: createFieldResource(deps),
+        option: createOptionResource(deps)
+      };
+    };
+    this.tenant = buildScope;
+    const root = buildScope(options.partition ?? 0);
+    this.candidate = root.candidate;
+    this.job = root.job;
+    this.client = root.client;
+    this.process = root.process;
+    this.resume = root.resume;
+    this.attachment = root.attachment;
+    this.user = root.user;
+    this.field = root.field;
+    this.option = root.option;
     this.partition = createPartitionResource({ requester, host: options.host });
-    this.user = createUserResource(deps);
-    this.field = createFieldResource(deps);
-    this.option = createOptionResource(deps);
   }
   /** The configured API host. */
   get host() {