@joymerrevent/porters-connect 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@
 
 ## [Unreleased]
 
+## [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
+
+- **Read クエリ面の拡充**（F-2 / ADR-0038・ADR-0005 R-5）。データ系の `search` / `searchAll` が次を受けます。
+  - `order` — 並び順 `[{ 項目: "asc" | "desc" }]`（数値・日時・System 型のみ）。
+  - `keywords` — テキスト項目の AND キーワード検索（`string[]`・カンマ込み 100 文字まで。超過は送信前に `PortersConfigError`）。
+  - `itemstate` — `"existing"`（既定）/ `"deleted"` / `"all"`。削除 API 非提供下で**削除済みデータを読む唯一の手段**
+    （`condition` は `P_Id` / `P_UpdateDate` / `P_UpdatedBy` に限定・実行時ガード／更新日 90 日以内は PORTERS 側が自動付与）。
+  - 新規 export 型 `Condition` / `Order` / `ItemState` / `SearchQuery`。
+
+### Changed
+
+- **（破壊的）`condition` を型安全化**。`{ "Person.P_Name:part": "山田" }`（loose な `Record<string,string>`）から
+  **`{ P_Name: { part: "山田" } }`**（項目の Data Type が許す演算子だけを受ける型付き形・ADR-0038 案1a）へ変更。
+  日時の値は ISO 8601（UTC `…Z`）で渡すと PORTERS 形式へ自動変換。**pre-1.0 のため minor**。
+  - 移行: キーを `"Alias:suffix"` から**接頭辞なしの項目名**へ、値を `{ suffix: 値 }` へ。
+    例 `{ "Person.P_Id:eq": "1" }` → `{ P_Id: { eq: 1 } }`。テキスト項目は `eq` 不可（`part` / `full`）。
+
 ## [0.3.0] - 2026-06-23
 
 ### Added
@@ -81,7 +112,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.3.0...HEAD
+[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.5.0...HEAD
+[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
 [0.2.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.1.1...v0.2.0

package/README.md

@@ -56,12 +56,17 @@ 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
 });
 
-// 検索（最大 200 件/ページ）
+// 複数 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: { "Person.P_Name:part": "山田" }, // 部分一致
+  condition: { P_Name: { part: "山田" } }, // テキストは part（部分一致）/ full（完全一致）
+  order: [{ P_UpdateDate: "desc" }], // 並び順（数値・日時・System のみ）
   count: 50,
 });
 console.log(page.total, page.items.length);
@@ -72,12 +77,14 @@ console.log(one?.P_Name);
 
 // 全件を自動ページング（200 件刻み）
 for await (const c of porters.candidate.searchAll({
-  condition: { "Person.P_Prefecture:eq": "東京都" },
+  condition: { P_Prefecture: { full: "東京都" } },
 })) {
   // c は 1 件ずつ
 }
 ```
 
+> 複数 partition を 1 つの App で扱う（マルチテナント SaaS）場合の `porters.tenant(id)` スコープ・テナント別 client・partition 発見は [マルチテナント ガイド][multi-tenancy] にまとめています。
+>
 > 認証情報やホスト名は**コミットしない**でください。`.env.example` を参考に `.env` で渡します。
 
 ## 契約なしで試す（オフライン評価）
@@ -172,16 +179,21 @@ await porters.auth.exchangeAuthorizationCode(code);
 - `create(input)` → 採番された **id（number）**。
 - `update(id, input)` → その **id**。
 
-**検索クエリ**（`query`）の主なキー：
+**検索クエリ**（`query`）の主なキー（すべて型安全。**項目の Data Type が許す演算子だけ**を受けます）：
 
 - `field`：取得する項目（接頭辞付き alias の配列。例 `["Person.P_Id", "Person.P_Name"]`）。
   **省略するとカタログ上の全項目を既定取得**します（PORTERS は field 未指定だと主キーのみ返すため、
   ライブラリが既定 field を補います）。`field: []`（空配列）を渡すと API 仕様どおり**主キーのみ**を返します（件数取得など）。
-- `condition`：検索条件。`{ "[Alias]:[suffix]": "値" }` 形式。`suffix` は型ごとに
-  `eq`/`gt`/`ge`/`le`/`lt`（数値・日時）、`part`/`full`（テキスト）、`or`/`and`（Option）。
+- `condition`：検索条件。`{ 項目: { 演算子: 値 } }` 形式（複数項目は AND）。演算子は Data Type ごとに
+  `eq`/`gt`/`ge`/`le`/`lt`（数値・日時・Id）、`part`/`full`（テキスト）、`or`/`and`（Option・参照/ユーザー型は ID）。
+  **日時の値は ISO 8601（UTC `…Z`）**で渡すと PORTERS 形式へ自動変換します。
+- `order`：並び順。`[{ 項目: "asc" | "desc" }]`（数値・日時・System 型のみ）。
+- `keywords`：テキスト項目のキーワード AND 検索（`string[]`・カンマ込み **100 文字まで**）。
+- `itemstate`：`"existing"`（既定）/ `"deleted"` / `"all"`。削除済みデータの取得。
 - `count`（1–200・既定 10）、`start`（0 始まり）。
 
-> **削除 API はありません**（PORTERS 仕様）。`delete()` メソッドは提供しません。削除済みは検索の状態フィルタで扱います。
+> **削除 API はありません**（PORTERS 仕様）。`delete()` メソッドは提供しません。削除済みは `itemstate: "deleted"` で読みます
+> （`condition` は `P_Id` / `P_UpdateDate` / `P_UpdatedBy` に限られ、更新日は 90 日以内）。
 
 ### マスタ Read（読み取り専用）
 
@@ -359,6 +371,7 @@ 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
 [sandbox]: ./examples/offline-sandbox.ts
 [adr]: ./docs/adr/README.md
 [design]: ./docs/design/basic-design.md

package/dist/index.d.ts

@@ -161,7 +161,75 @@ type ResourcePage<F extends FieldCatalog> = {
     start: number;
 };
 
-type SearchQuery = {
+/** Comparable ops for numeric Ids (System[Id]); `or` matches a set of Resource Ids (`P_Id:or=1:2`). */
+type IdCondition = {
+    gt?: number;
+    ge?: number;
+    eq?: number;
+    le?: number;
+    lt?: number;
+    or?: number[];
+};
+/** Comparable ops for Number. */
+type NumberCondition = {
+    gt?: number;
+    ge?: number;
+    eq?: number;
+    le?: number;
+    lt?: number;
+};
+/** Comparable ops for date/time fields. Values are ISO 8601 (UTC `…Z`); normalised to PORTERS on send. */
+type TemporalCondition = {
+    gt?: string;
+    ge?: string;
+    eq?: string;
+    le?: string;
+    lt?: string;
+};
+/** Text match. `full` = exact, `part` = substring (PORTERS default). */
+type TextCondition = {
+    full?: string;
+    part?: string;
+};
+/** Option-select match; values are option aliases (e.g. `Option.P_SE`), OR/AND-joined. */
+type OptionCondition = {
+    or?: string[];
+    and?: string[];
+};
+/** Link/reference match by id (User / System[Reference]): `eq` one id, or OR/AND a set of ids. */
+type ReferenceCondition = {
+    eq?: number;
+    or?: number[];
+    and?: number[];
+};
+/** The condition-operator object a field of Data Type `D` accepts. */
+type ConditionFor<D extends DataType> = D extends "System[Id]" ? IdCondition : D extends "Number" ? NumberCondition : D extends "DateTime" | "System[DateTime]" | "Date" | "Age" ? TemporalCondition : D extends "SinglelineText" | "MultilineText" | "Mail" | "Telephone" | "URL" ? TextCondition : D extends "Option" ? OptionCondition : D extends "User" | "System[Reference]" ? ReferenceCondition : never;
+/**
+ * A typed search condition over a catalog: each field maps to the operator object its Data Type
+ * allows (ADR-0038 案1a). Multiple fields are AND-joined (reference). Unknown aliases / wrong
+ * operators are type errors. Custom `U_`/`A_` fields are not in the catalog — condition on them via
+ * a cast (the encoder passes unknown aliases through as raw scalars, like read/write).
+ */
+type Condition<F extends FieldCatalog> = {
+    [K in keyof F]?: ConditionFor<F[K]>;
+};
+type OrderableDataType = "System[Id]" | "System[DateTime]" | "Number" | "DateTime" | "Date" | "Age";
+type OrderableKeys<F extends FieldCatalog> = {
+    [K in keyof F]: F[K] extends OrderableDataType ? K : never;
+}[keyof F];
+/**
+ * Sort spec: an ordered list of `{ field: "asc" | "desc" }`, encoded in array (then key) order. Only
+ * orderable Data Types (Number/Date/DateTime/Age/System) are accepted (reference).
+ */
+type Order<F extends FieldCatalog> = Array<Partial<Record<OrderableKeys<F>, "asc" | "desc">>>;
+/**
+ * Which delete state to read. Omitting (or `existing`) reads live data; `deleted`/`all` read deleted
+ * records — the only way to read deleted data, since there is no delete API. When `deleted`/`all`,
+ * condition is restricted to `P_Id` / `P_UpdateDate` / `P_UpdatedBy` and PORTERS auto-adds a
+ * "updated within 90 days" filter (`P_UpdateDate` = the delete time, `P_UpdatedBy` = the last editor).
+ */
+type ItemState = "existing" | "deleted" | "all";
+type SearchQuery<F extends FieldCatalog = FieldCatalog> = {
     /**
      * Output fields as prefixed aliases (e.g. `Person.P_Name`). **Omit** to fetch every catalogued
      * field by default (ADR-0020): PORTERS returns only the primary key for a fieldless request, so
@@ -169,10 +237,21 @@ type SearchQuery = {
      * API-native "primary key only" response (e.g. counting). A non-empty list is sent verbatim.
      */
     field?: string[];
-    condition?: Record<string, string>;
+    /** Typed AND-conditions; each field's operators derive from its Data Type (ADR-0038). */
+    condition?: Condition<F>;
+    /** Sort order; orderable Data Types only (Number/Date/DateTime/Age/System). */
+    order?: Order<F>;
+    /**
+     * Keyword AND-search over text fields (MultilineText/SinglelineText/Mail/URL; Telephone digits
+     * only). OR is not supported. Max 100 characters including commas — guarded before send.
+     */
+    keywords?: string[];
+    /** Delete-state filter (default `existing`). `deleted`/`all` restrict `condition` — see {@link ItemState}. */
+    itemstate?: ItemState;
     count?: number;
     start?: number;
 };
+
 type WritableKeys<F extends FieldCatalog> = {
     [K in keyof F]: F[K] extends WritableDataType ? K : never;
 }[keyof F];
@@ -190,9 +269,9 @@ type UpdateInput<F extends FieldCatalog> = {
     [K in WritableKeys<F>]?: WriteValueOf<F[K]> | null;
 };
 type Resource<F extends FieldCatalog, Req extends keyof F> = {
-    search(query?: SearchQuery): Promise<ResourcePage<F>>;
+    search(query?: SearchQuery<F>): Promise<ResourcePage<F>>;
     /** Auto-paginating search: yields every matching record (200 per page). */
-    searchAll(query?: Omit<SearchQuery, "count" | "start">): AsyncIterable<ReadRecord<F>>;
+    searchAll(query?: Omit<SearchQuery<F>, "count" | "start">): AsyncIterable<ReadRecord<F>>;
     get(id: number): Promise<ReadRecord<F> | undefined>;
     /** Create one record; resolves to the newly assigned id. */
     create(input: CreateInput<F, Req>): Promise<number>;
@@ -224,7 +303,7 @@ declare const REQUIRED_ON_CREATE$4: readonly ["P_Owner"];
 /** A decoded Candidate: known `P_` fields, each requested field `value | null`. */
 type Candidate = ReadRecord<typeof FIELDS$8>;
 type CandidatePage = ResourcePage<typeof FIELDS$8>;
-type CandidateSearchQuery = SearchQuery;
+type CandidateSearchQuery = SearchQuery<typeof FIELDS$8>;
 /** Fields for `create`: `P_Owner` is required; `P_Id` / system timestamps are not settable. */
 type CandidateCreateInput = CreateInput<typeof FIELDS$8, (typeof REQUIRED_ON_CREATE$4)[number]>;
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
@@ -272,7 +351,7 @@ declare const REQUIRED_ON_CREATE$3: readonly ["P_Owner", "P_Client", "P_Recruite
 /** A decoded Job: known `P_` fields, each requested field `value | null`. */
 type Job = ReadRecord<typeof FIELDS$7>;
 type JobPage = ResourcePage<typeof FIELDS$7>;
-type JobSearchQuery = SearchQuery;
+type JobSearchQuery = SearchQuery<typeof FIELDS$7>;
 /** Fields for `create`: `P_Owner` required; `P_Id` / system timestamps are not settable. */
 type JobCreateInput = CreateInput<typeof FIELDS$7, (typeof REQUIRED_ON_CREATE$3)[number]>;
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
@@ -304,7 +383,7 @@ declare const REQUIRED_ON_CREATE$2: readonly ["P_Owner"];
 /** A decoded Client (company): known `P_` fields, each requested field `value | null`. */
 type Client = ReadRecord<typeof FIELDS$6>;
 type ClientPage = ResourcePage<typeof FIELDS$6>;
-type ClientSearchQuery = SearchQuery;
+type ClientSearchQuery = SearchQuery<typeof FIELDS$6>;
 /** Fields for `create`: `P_Owner` required; `P_Id` / system timestamps are not settable. */
 type ClientCreateInput = CreateInput<typeof FIELDS$6, (typeof REQUIRED_ON_CREATE$2)[number]>;
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
@@ -337,7 +416,7 @@ declare const REQUIRED_ON_CREATE$1: readonly ["P_Owner", "P_Client", "P_Recruite
  *  requested field `value | null`. */
 type Process = ReadRecord<typeof FIELDS$5>;
 type ProcessPage = ResourcePage<typeof FIELDS$5>;
-type ProcessSearchQuery = SearchQuery;
+type ProcessSearchQuery = SearchQuery<typeof FIELDS$5>;
 /** Fields for `create`: `P_Owner` required; `P_Id` / system timestamps are not settable. */
 type ProcessCreateInput = CreateInput<typeof FIELDS$5, (typeof REQUIRED_ON_CREATE$1)[number]>;
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
@@ -382,7 +461,7 @@ declare const REQUIRED_ON_CREATE: readonly ["P_Owner", "P_Candidate"];
  *  `value | null`. */
 type Resume = ReadRecord<typeof FIELDS$4>;
 type ResumePage = ResourcePage<typeof FIELDS$4>;
-type ResumeSearchQuery = SearchQuery;
+type ResumeSearchQuery = SearchQuery<typeof FIELDS$4>;
 /** Fields for `create`: `P_Owner` required; `P_Id` / system timestamps are not settable. */
 type ResumeCreateInput = CreateInput<typeof FIELDS$4, (typeof REQUIRED_ON_CREATE)[number]>;
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
@@ -635,7 +714,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;
@@ -650,6 +733,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`
@@ -673,6 +772,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;
@@ -726,4 +835,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 CustomDataType, type DefinedFields, type ErrorCategory, type Field, type FieldBuilder, type FieldDecls, type FieldDef, type FieldPage, type FieldResource, type FieldSearchQuery, type FieldValue, type GetAccessTokenOptions, 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 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 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 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

@@ -703,6 +703,83 @@ var paginate = async function* (fetchPage) {
   }
 };
 
+// src/resources/query.ts
+var KEYWORDS_MAX_CHARS = 100;
+var DELETED_CONDITION_FIELDS = /* @__PURE__ */ new Set([
+  "P_Id",
+  "P_UpdateDate",
+  "P_UpdatedBy"
+]);
+var serializeConditionValue = (type, value) => {
+  if (Array.isArray(value)) return value.map(String).join(":");
+  if (type === "DateTime" || type === "System[DateTime]") {
+    return isoToPortersDateTime(String(value));
+  }
+  if (type === "Date" || type === "Age") return isoToPortersDate(String(value));
+  return String(value);
+};
+var encodeCondition = (condition, itemstate, ctx) => {
+  const restricted = itemstate === "deleted" || itemstate === "all";
+  const parts = [];
+  for (const [alias, ops] of Object.entries(condition)) {
+    if (ops === void 0) continue;
+    if (restricted && !DELETED_CONDITION_FIELDS.has(alias)) {
+      throw new PortersConfigError(
+        `condition field "${alias}" is not allowed when itemstate is "${itemstate}"`,
+        {
+          category: "config",
+          hint: "Deleted reads (itemstate deleted/all) accept only P_Id, P_UpdateDate, P_UpdatedBy in condition."
+        }
+      );
+    }
+    const type = ctx.fields.get(alias);
+    for (const [suffix, value] of Object.entries(ops)) {
+      if (value === void 0) continue;
+      parts.push(
+        `${ctx.prefix}.${alias}:${suffix}=${serializeConditionValue(type, value)}`
+      );
+    }
+  }
+  return parts.join(",");
+};
+var encodeOrder = (order, ctx) => {
+  const parts = [];
+  for (const spec of order) {
+    const dirs = spec;
+    for (const [alias, dir] of Object.entries(dirs)) {
+      if (dir === void 0) continue;
+      parts.push(`${ctx.prefix}.${alias}:${dir}`);
+    }
+  }
+  return parts.join(",");
+};
+var appendReadQuery = (p, q, ctx) => {
+  if (q.condition) {
+    const cond = encodeCondition(q.condition, q.itemstate, ctx);
+    if (cond.length > 0) p.set("condition", cond);
+  }
+  if (q.order) {
+    const order = encodeOrder(q.order, ctx);
+    if (order.length > 0) p.set("order", order);
+  }
+  if (q.keywords && q.keywords.length > 0) {
+    const kw = q.keywords.join(",");
+    if (kw.length > KEYWORDS_MAX_CHARS) {
+      throw new PortersConfigError(
+        `keywords is ${kw.length} characters, over the ${KEYWORDS_MAX_CHARS}-character limit`,
+        {
+          category: "config",
+          hint: "Shorten keywords: PORTERS caps the keyword search at 100 characters including commas."
+        }
+      );
+    }
+    p.set("keywords", kw);
+  }
+  if (q.itemstate !== void 0 && q.itemstate !== "existing") {
+    p.set("itemstate", q.itemstate);
+  }
+};
+
 // src/resources/resource.ts
 var USER_SUBFIELDS = ["P_Id", "P_Type", "P_Name", "P_Mail"];
 var defaultFieldList = (prefix, fields) => Object.entries(fields).map(
@@ -726,14 +803,11 @@ var firstWriteResultId = (body, path, name) => {
   }
   return first.id;
 };
-var buildReadUrl = (host, partition, path, q) => {
+var buildReadUrl = (host, partition, path, q, ctx) => {
   const p = new URLSearchParams();
   p.set("partition", String(partition));
   if (q.field && q.field.length > 0) p.set("field", q.field.join(","));
-  if (q.condition) {
-    const conds = Object.entries(q.condition).map(([k, v]) => `${k}=${v}`);
-    if (conds.length > 0) p.set("condition", conds.join(","));
-  }
+  appendReadQuery(p, q, ctx);
   if (q.count !== void 0) p.set("count", String(q.count));
   if (q.start !== void 0) p.set("start", String(q.start));
   return `https://${host}/v1/${path}?${p.toString()}`;
@@ -743,7 +817,10 @@ var createResource = (config, deps) => {
   const fieldMap = new Map(Object.entries(config.fields));
   const decode = decoderFor(config.fields);
   const defaultFields = defaultFieldList(config.prefix, config.fields);
-  const readUrl = (q) => buildReadUrl(deps.host, deps.partition, config.path, q);
+  const readUrl = (q) => buildReadUrl(deps.host, deps.partition, config.path, q, {
+    prefix: config.prefix,
+    fields: fieldMap
+  });
   const writeUrl = () => buildWriteUrl(deps.host, deps.partition, config.path);
   const firstWriteId = (body) => firstWriteResultId(body, config.path, config.name);
   const search = (query = {}) => runRead(
@@ -753,10 +830,8 @@ var createResource = (config, deps) => {
   );
   const searchAll = (query = {}) => paginate((count, start) => search({ ...query, count, start }));
   const get = async (id) => {
-    const page = await search({
-      condition: { [`${config.prefix}.P_Id:eq`]: String(id) },
-      count: 1
-    });
+    const condition = { P_Id: { eq: id } };
+    const page = await search({ condition, count: 1 });
     return page.items[0];
   };
   const write = (item, idempotent) => deps.requester.request(
@@ -1023,6 +1098,18 @@ var DEFAULT_FIELDS = [
   "ContentType",
   "FileName"
 ];
+var buildAttachmentReadUrl = (host, partition, q) => {
+  const p = new URLSearchParams();
+  p.set("partition", String(partition));
+  if (q.field && q.field.length > 0) p.set("field", q.field.join(","));
+  if (q.condition) {
+    const conds = Object.entries(q.condition).map(([k, v]) => `${k}=${v}`);
+    if (conds.length > 0) p.set("condition", conds.join(","));
+  }
+  if (q.count !== void 0) p.set("count", String(q.count));
+  if (q.start !== void 0) p.set("start", String(q.start));
+  return `https://${host}/v1/attachment?${p.toString()}`;
+};
 var numOrNull = (v) => {
   const s = asString(v);
   return s === void 0 ? null : Number(s);
@@ -1048,7 +1135,7 @@ var createAttachmentResource = (deps) => {
   const search = (query = {}) => deps.requester.request(
     {
       method: "GET",
-      url: buildReadUrl(deps.host, deps.partition, "attachment", {
+      url: buildAttachmentReadUrl(deps.host, deps.partition, {
         ...query,
         field: query.field ?? DEFAULT_FIELDS
       }),
@@ -1252,6 +1339,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();
@@ -1286,22 +1383,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() {