@joymerrevent/porters-connect 0.22.0 → 0.24.0

package/CHANGELOG.md

@@ -5,6 +5,129 @@
 
 ## [Unreleased]
 
+## [0.24.0] - 2026-09-24
+
+**トークンの取り方と置き場所を別々に渡せるようにした版**です。**破壊的変更を 2 つ**含みます
+（構築オプション `auth` の廃止と、日時（`DateTime`）に渡す値の制限）。あわせて、Refresh Token が拒否されたときに
+回復しなかった不具合を直し、使い方ドキュメントを実装と突き合わせて直しました。
+
+### Changed
+
+- **（破壊的）トークンの取り方を `tokenProvider` で、置き場所を `tokenStore` で別々に渡すようになりました**
+  （[ADR-0091][adr91]）。キャッシュ・期限の判断・失効時の取り直し・同時呼び出しの 1 本化・`tokenStore` への保存は、
+  既定の取り方でも、渡した取り方でもクライアントが受け持ちます。これまで取り方を差し替えるには
+  `getAccessToken` を丸ごと自前で書くしかなく、期限の判断や同時呼び出しのまとめ方まで利用者の実装に任されていました。
+
+  ```ts
+  // 変更前
+  const porters = new PortersClient({
+    hostname,
+    auth: { getAccessToken: async () => await myTokenService.get() },
+  });
+
+  // 変更後
+  const porters = new PortersClient({
+    hostname,
+    tokenProvider: {
+      acquire: async () => ({
+        accessToken: { token: await myTokenService.get() },
+      }),
+    },
+  });
+  ```
+
+  - `TokenProvider` は `{ acquire, refresh?, exchange? }` です。`acquire` は必須、`refresh` と `exchange` は
+    使うときだけ渡します。期限（`expiresAt`）を返せば、その 60 秒前に取り直します。
+  - **構築オプション `auth` は無くなりました**。`auth` や、`getAccessToken` だけを持つ古い形を渡すと、構築時に
+    `PortersConfigError`（`category: "config"`）で止まります（型でも弾きます）。
+  - **`StoredTokens` の形が変わりました**: `{ accessToken: { token, expiresAt? }, refreshToken?: { token, expiresAt? } }`。
+    `tokenStore` に以前の形で保存されていた値は「保存なし」として扱い、上げた直後の 1 回だけ `code_direct` で
+    取り直します（保存先を手で消す必要はありません）。
+  - `tokenStore` は `tokenProvider` を渡したときも使われます。
+  - `porters.auth` の 6 メソッドは、どの取り方でも動きます。`exchangeAuthorizationCode` には `tokenProvider` の
+    `exchange` が、`authorizationUrl` / `revokeUrl` には `appId` が要ります。
+  - 既定の取り方で `appId` / `appSecret` が無いときは、PORTERS へ何も送らずに `PortersConfigError` になります。
+  - 保存済みの Access Token がまだ有効なら、起動直後にも取りに行きません。
+  - `GetAccessTokenOptions` を公開 API から外し、`IssuedToken`（`{ token, expiresAt? }`）を足しました。
+  - 書き方は[認証とトークン][oauth-guide]の「トークンの取り方を差し替える」にあります。
+
+- **（破壊的）日時（`DateTime` / `System[DateTime]`）の項目に書く値と、`condition` に書く値は、時刻とタイムゾーンの
+  そろった ISO 8601 だけを受け付けるようになりました**。形は `YYYY-MM-DDTHH:MM[:SS[.sss]]` に `Z` か `±HH:MM` が
+  付いたものです。`new Date().toISOString()` の出力はそのまま渡せます。
+
+  これまでは、次の値が送る前に止まらず、**ずれた値が PORTERS に届いていました**。
+
+  | 渡した値                                 | これまで（実行環境が日本時間のとき） | これから             |
+  | ---------------------------------------- | ------------------------------------ | -------------------- |
+  | `"2026/09/10"`（PORTERS の形式）         | `2026/09/09 15:00:00` として送る     | `PortersConfigError` |
+  | `"2026-09-10T12:00:00"`（ゾーン無し）    | 実行環境のタイムゾーンで読んで送る   | `PortersConfigError` |
+  | `"2026-09-10"`（日付だけ）               | UTC の 0 時として送る                | `PortersConfigError` |
+  | `"2026-02-30T00:00:00Z"` / `…T24:00:00Z` | 3/2・翌日に繰り上げて送る            | `PortersConfigError` |
+  - エラーは `PortersConfigError`（`category: "validation"`）で、`hint` がゾーンの要ることを示します。
+  - 日本時間で考えているなら、`"2026-09-10T09:00:00+09:00"` のようにオフセットを付けて渡します。
+  - `Date` / `Age` の項目（日付だけ）は変わりません。
+
+### Fixed
+
+- **既定の取り方で、PORTERS が Refresh Token を受け付けなかったとき（期限切れ・無効）に、`code_direct` で取り直す
+  ようになりました**。手元に記録した期限がまだ先だと、これまでは同じ refresh を繰り返して `PortersAuthError` になり、
+  `porters.auth.clearTokens()` を呼ぶまで回復しませんでした。同じ `tokenStore` を使う別のプロセスが先に更新して、
+  手元の Refresh Token が古くなったときにも起きていました。`PortersAuthError` が返るのは、`code_direct` でも
+  取り直せないとき（初回の権限付与が済んでいない・取り消された、App ID / App Secret が違う、など）だけです。
+  渡した `tokenProvider` の失敗は、これまでどおりそのまま届けます。
+- トークンの取得が認証 API の 401 / 402 で失敗したときに、Access Token の期限切れと取り違えて、もう一度取り直しを
+  強いていたのをやめました（失敗する取得を 2 回送っていました）。
+- **使い方ドキュメントを実装と突き合わせ、挙動と食い違っていた記述を直しました**。主なもの:
+  `create` を自動で再送しないのは届いたか分からないときだけ／エラーの型と HTTP ステータスの対応／
+  Activity の `P_ResourceId` は `expand` できない／Attachment の `search` で絞れるのは `resourceId` だけ／
+  一括書き込みは約 15000 字でも分ける／`base64ToBytes` は読めない文字列で例外を投げる、など。
+  トークンの取得や OAuth の URL 作成で出る `PortersConfigError` を、メッセージから
+  [トラブルシューティング][troubleshooting]で引けるようにしました。
+
+## [0.23.0] - 2026-09-24
+
+**カスタム項目を宣言で `create` の必須にできるようにした版**です。あわせて、利用者の TypeScript の下限を
+**5.4** と定め、それより古い版でははっきりした型エラーになるようにしました。**TypeScript 5.4 より前を使っている
+場合は破壊的変更です**（下の Changed）。
+
+### Added
+
+- **カスタム項目を宣言で `create` の必須にできるようになりました**（[ADR-0089][adr89]）。宣言のビルダーに
+  `{ required: true }` を渡すと、その項目は `create` / `createMany` の入力型で必須になります。
+
+  ```ts
+  const fields = defineFields({
+    candidate: (f) => ({
+      U_score: f.number({ required: true }), // create で必須
+      U_source: f.option(), // 任意のまま
+    }),
+  });
+  const t = porters.tenant(1, { fields });
+
+  await t.candidate.create({ P_Owner: 5, U_score: 80 }); // U_score を渡さないとコンパイルエラー
+  ```
+
+  - `required` を書かなければ、これまでと同じく任意です。`update` / `updateMany` では常に任意です。
+  - 型で止めるだけで、実行時には検査しません（標準項目の必須と同じ扱い）。
+  - `TenantScope<typeof fields>` と書いた型でも必須になります。新しい型引数は要りません。
+  - `generateFieldDecls` は、テナントが入力必須にしている項目（Field Read の `P_Required` が `1`）に
+    `{ required: true }` を付けて出します。`create` で必須にしない項目は、生成したファイルから消します。
+  - `readCustomCatalog` の戻り値に `required`（alias → 入力必須かどうか）が増えました。
+  - `verifyFields` の報告に `requiredMismatch`（宣言の `required` とテナントの入力必須の食い違い）が増えました。
+    読み書きは壊れないので、`ok` は変わらず、`assertFieldsMatch` も止めません。
+  - 新しく公開した型: `FieldOptions` / `RequiredFor` / `DeclaredRequiredOf` / `RequiredMismatch`。
+
+### Changed
+
+- **（TypeScript 5.4 より前を使っている場合は破壊的）型を読むには TypeScript 5.4 以上が要ります**
+  （[ADR-0090][adr90]）。同梱の型定義が、5.4 で入った型（`NoInfer`）を使うためです。5.4 より前の TypeScript では、
+  このパッケージから `import` したものを使った行が、`requires TypeScript 5.4 or later` を含む型エラーになります。
+  そのときは TypeScript を上げてください。`bundler` / `node16` / `node` のどの解決方式でも同じです。
+- **`verifyFields` の報告を自分で組み立てているコード**（テストのスタブなど）は、`requiredMismatch: []` を
+  足してください。`FieldVerification` に項目が増えたためで、`verifyFields` の戻り値を読むだけのコードは変わりません。
+- 内部の検査を増やしました（利用者への影響はありません）。CI で、TypeScript の下限の版（5.4 の系で最も古い安定版）と
+  開発で使う版で利用者のコードをコンパイルし、下限より前の版では上の型エラーになることを確かめます。
+
 ## [0.22.0] - 2026-09-23
 
 **読み取りの値の検証を 1 つ増やし、使い方ドキュメントを組み直した版**です。破壊的変更はありませんが、
@@ -1333,7 +1456,9 @@ Attachment）あるのに、受け口の形が 3 つとも違っていました
 [ref]: docs/usage/reference/README.md
 [kac]: https://keepachangelog.com/en/1.1.0/
 [semver]: https://semver.org/
-[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.22.0...HEAD
+[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.24.0...HEAD
+[0.24.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.23.0...v0.24.0
+[0.23.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.22.0...v0.23.0
 [0.22.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.21.0...v0.22.0
 [0.21.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.20.1...v0.21.0
 [0.20.1]: https://github.com/Joymerrevent/porters-connect/compare/v0.20.0...v0.20.1
@@ -1374,3 +1499,7 @@ Attachment）あるのに、受け口の形が 3 つとも違っていました
 [adr87]: docs/adr/0087-tenant-scoped-field-declarations.md
 [howto-custom-fields]: docs/usage/topics/custom-fields.md
 [ref-department]: docs/usage/reference/resource-api/resources/department.md
+[adr89]: docs/adr/0089-custom-field-required-on-create.md
+[adr90]: docs/adr/0090-typescript-floor.md
+[adr91]: docs/adr/0091-token-provider-and-store.md
+[troubleshooting]: docs/usage/reference/troubleshooting.md

package/README.md

@@ -34,7 +34,7 @@ XML レスポンスを型付きオブジェクトに変換し、独自仕様の
 4. **付与するスコープ**の決定（リソース別に `_r` / `_w`。Read でも複数要ることがあります）。
 
 揃えかたは[始める前に][s-prereq]に、権限付与の手順は[認証を通して、疎通を確認する][s-auth]に
-あります。実行環境は **Node.js 22.12 以上**で、型定義は同梱です。ビルド済みの JavaScript ファイルは ESM（`import`）の 1 つですが、
+あります。実行環境は **Node.js 22.12 以上**で、型定義は同梱です（型を読むには **TypeScript 5.4 以上**が要ります）。ビルド済みの JavaScript ファイルは ESM（`import`）の 1 つですが、
 CJS（`require`）からも `require("@joymerrevent/porters-connect")` で読めます（[CJS から使う][s-cjs]）。
 
 契約や権限付与を**待っている間**も、PORTERS に繋がずにコードとテストは書けます

package/dist/index.d.cts

@@ -1,22 +1,42 @@
-/** Options for {@link TokenProvider.getAccessToken}. */
-type GetAccessTokenOptions = {
-    /** Force a refresh even if the cached token looks valid (reactive 401/402). */
-    forceRefresh?: boolean;
+/** One token and, when known, its absolute expiry (epoch ms). No `expiresAt` means "unknown". */
+type IssuedToken = {
+    token: string;
+    expiresAt?: number;
 };
-/** Supplies a valid Access Token, refreshing transparently when expired. */
-type TokenProvider = {
-    getAccessToken(opts?: GetAccessTokenOptions): Promise<string>;
-};
-/** Tokens persisted by a {@link TokenStore} (expiry is absolute epoch ms). */
+/**
+ * Tokens as obtained from a {@link TokenProvider} and persisted by a {@link TokenStore}.
+ * `refreshToken` is present only when the issuer hands one out; a value and its expiry always
+ * travel together.
+ */
 type StoredTokens = {
-    accessToken: string;
-    refreshToken: string;
-    accessTokenExpiresAt: number;
-    refreshTokenExpiresAt: number;
+    accessToken: IssuedToken;
+    refreshToken?: IssuedToken;
+};
+/**
+ * Where tokens come from. Pass one as `tokenProvider` to obtain tokens elsewhere (for example
+ * from a central service that holds the App Secret); leave it out for the built-in `code_direct`
+ * flow. The client caches what these return, renews shortly before expiry, retries once on an
+ * expired-token response, collapses concurrent renewals into one, and saves to `tokenStore`.
+ */
+type TokenProvider = {
+    /** Obtain tokens from scratch. Called first, and whenever renewal is not possible. */
+    acquire(): Promise<StoredTokens>;
+    /**
+     * Renew tokens. Called instead of {@link TokenProvider.acquire} while `current.refreshToken`
+     * is usable — or, when the issuer hands out no refresh token, whenever renewal is needed.
+     * Leave it out to renew by calling `acquire` again.
+     */
+    refresh?(current: StoredTokens): Promise<StoredTokens>;
+    /**
+     * Exchange an authorization `code` returned to your redirect URL after the browser grant.
+     * Needed only for `porters.auth.exchangeAuthorizationCode`. PORTERS expires a `code` 30 seconds
+     * after issuing it, so do not do slow work here.
+     */
+    exchange?(code: string): Promise<StoredTokens>;
 };
 /**
  * Pluggable token persistence (default: in-memory). Async so it can back onto
- * redis / DB / file for multi-instance server use.
+ * redis / DB / file for multi-instance server use. Used with every token provider.
  */
 type TokenStore = {
     get(): Promise<StoredTokens | undefined>;
@@ -146,18 +166,18 @@ type RevokeUrlOptions = AuthorizationUrlOptions;
  * The `porters.auth.*` surface. The initial per-Company-DB grant
  * needs a human to open {@link AuthApi.authorizationUrl} in a browser and consent; the
  * library only builds the URL and exchanges the returned `code`. Day-to-day token
- * acquisition/refresh stays transparent (the default strategy), so most callers never
- * touch this surface.
+ * acquisition and renewal are handled by the client, whichever token provider is in use, so
+ * most callers never touch this surface.
  */
 type AuthApi = {
     /** Build the browser `code`-grant URL to open for the initial permission grant. */
     authorizationUrl(opts: AuthorizationUrlOptions): string;
     /**
-     * Exchange a redirect `?code=` for tokens and save them into the default strategy.
-     * Resolves `void` on success (tokens are stored internally — inspect via
-     * {@link AuthApi.getToken}); throws on failure: {@link PortersConfigError} (missing
-     * credentials / custom strategy), `PortersAuthError` (token-endpoint error or expired
-     * code), or `PortersNetworkError`.
+     * Exchange a redirect `?code=` for tokens through the token provider's `exchange`, and save
+     * them (cache and `tokenStore`). Resolves `void` on success (inspect via
+     * {@link AuthApi.getToken}); rejects with {@link PortersConfigError} when the provider has no
+     * `exchange` or the built-in one lacks `appId` / `appSecret`, `PortersAuthError` (token-endpoint
+     * error or expired code), or `PortersNetworkError`.
      */
     exchangeAuthorizationCode(code: string): Promise<void>;
     /**
@@ -776,7 +796,7 @@ type CandidateCreateInput = CreateInput<typeof FIELDS$g, (typeof REQUIRED_ON_CRE
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
 type CandidateUpdateInput = UpdateInput<typeof FIELDS$g>;
 /** The Candidate accessor; `C` is the declared custom-field catalog merged on. */
-type CandidateResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$g & C, (typeof REQUIRED_ON_CREATE$b)[number]>;
+type CandidateResource<C extends FieldCatalog = EmptyCatalog, CR extends keyof C = never> = Resource<typeof FIELDS$g & C, (typeof REQUIRED_ON_CREATE$b)[number] | CR>;
 
 declare const FIELDS$f: {
     readonly P_Id: "System[Id]";
@@ -914,7 +934,7 @@ type JobCreateInput = CreateInput<typeof FIELDS$f, (typeof REQUIRED_ON_CREATE$a)
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
 type JobUpdateInput = UpdateInput<typeof FIELDS$f>;
 /** The Job accessor; `C` is the declared custom-field catalog merged on. */
-type JobResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$f & C, (typeof REQUIRED_ON_CREATE$a)[number], typeof REFERENCES$7>;
+type JobResource<C extends FieldCatalog = EmptyCatalog, CR extends keyof C = never> = Resource<typeof FIELDS$f & C, (typeof REQUIRED_ON_CREATE$a)[number] | CR, typeof REFERENCES$7>;
 
 declare const FIELDS$e: {
     readonly P_Id: "System[Id]";
@@ -947,7 +967,7 @@ type ClientCreateInput = CreateInput<typeof FIELDS$e, (typeof REQUIRED_ON_CREATE
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
 type ClientUpdateInput = UpdateInput<typeof FIELDS$e>;
 /** The Client accessor; `C` is the declared custom-field catalog merged on. */
-type ClientResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$e & C, (typeof REQUIRED_ON_CREATE$9)[number]>;
+type ClientResource<C extends FieldCatalog = EmptyCatalog, CR extends keyof C = never> = Resource<typeof FIELDS$e & C, (typeof REQUIRED_ON_CREATE$9)[number] | CR>;
 
 declare const FIELDS$d: {
     readonly P_Id: "System[Id]";
@@ -1015,7 +1035,7 @@ type RecruiterCreateInput = CreateInput<typeof FIELDS$d, (typeof REQUIRED_ON_CRE
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
 type RecruiterUpdateInput = UpdateInput<typeof FIELDS$d>;
 /** The Recruiter accessor; `C` is the declared custom-field catalog merged on. */
-type RecruiterResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$d & C, (typeof REQUIRED_ON_CREATE$8)[number], typeof REFERENCES$6>;
+type RecruiterResource<C extends FieldCatalog = EmptyCatalog, CR extends keyof C = never> = Resource<typeof FIELDS$d & C, (typeof REQUIRED_ON_CREATE$8)[number] | CR, typeof REFERENCES$6>;
 
 declare const FIELDS$c: {
     readonly P_Id: "System[Id]";
@@ -1083,7 +1103,7 @@ type ContactCreateInput = CreateInput<typeof FIELDS$c, (typeof REQUIRED_ON_CREAT
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
 type ContactUpdateInput = UpdateInput<typeof FIELDS$c>;
 /** The Contact accessor; `C` is the declared custom-field catalog merged on. */
-type ContactResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$c & C, (typeof REQUIRED_ON_CREATE$7)[number], typeof REFERENCES$5>;
+type ContactResource<C extends FieldCatalog = EmptyCatalog, CR extends keyof C = never> = Resource<typeof FIELDS$c & C, (typeof REQUIRED_ON_CREATE$7)[number] | CR, typeof REFERENCES$5>;
 
 declare const FIELDS$b: {
     readonly P_Id: "System[Id]";
@@ -1198,7 +1218,7 @@ type OpportunityCreateInput = CreateInput<typeof FIELDS$b, (typeof REQUIRED_ON_C
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
 type OpportunityUpdateInput = UpdateInput<typeof FIELDS$b>;
 /** The Opportunity accessor; `C` is the declared custom-field catalog merged on. */
-type OpportunityResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$b & C, (typeof REQUIRED_ON_CREATE$6)[number], typeof REFERENCES$4>;
+type OpportunityResource<C extends FieldCatalog = EmptyCatalog, CR extends keyof C = never> = Resource<typeof FIELDS$b & C, (typeof REQUIRED_ON_CREATE$6)[number] | CR, typeof REFERENCES$4>;
 
 declare const FIELDS$a: {
     readonly P_Id: "System[Id]";
@@ -1230,7 +1250,7 @@ type ActivityCreateInput = CreateInput<typeof FIELDS$a, (typeof REQUIRED_ON_CREA
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
 type ActivityUpdateInput = UpdateInput<typeof FIELDS$a>;
 /** The Activity accessor; `C` is the declared custom-field catalog merged on. */
-type ActivityResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$a & C, (typeof REQUIRED_ON_CREATE$5)[number]>;
+type ActivityResource<C extends FieldCatalog = EmptyCatalog, CR extends keyof C = never> = Resource<typeof FIELDS$a & C, (typeof REQUIRED_ON_CREATE$5)[number] | CR>;
 
 declare const FIELDS$9: {
     readonly P_Id: "System[Id]";
@@ -1311,7 +1331,7 @@ type ContractCreateInput = CreateInput<typeof FIELDS$9, (typeof REQUIRED_ON_CREA
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
 type ContractUpdateInput = UpdateInput<typeof FIELDS$9>;
 /** The Contract accessor; `C` is the declared custom-field catalog merged on. */
-type ContractResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$9 & C, (typeof REQUIRED_ON_CREATE$4)[number], typeof REFERENCES$3>;
+type ContractResource<C extends FieldCatalog = EmptyCatalog, CR extends keyof C = never> = Resource<typeof FIELDS$9 & C, (typeof REQUIRED_ON_CREATE$4)[number] | CR, typeof REFERENCES$3>;
 
 declare const FIELDS$8: {
     readonly P_Id: "System[Id]";
@@ -1751,7 +1771,7 @@ type SalesCreateInput = CreateInput<typeof FIELDS$8, (typeof REQUIRED_ON_CREATE$
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
 type SalesUpdateInput = UpdateInput<typeof FIELDS$8>;
 /** The Sales accessor; `C` is the declared custom-field catalog merged on. */
-type SalesResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$8 & C, (typeof REQUIRED_ON_CREATE$3)[number], typeof REFERENCES$2>;
+type SalesResource<C extends FieldCatalog = EmptyCatalog, CR extends keyof C = never> = Resource<typeof FIELDS$8 & C, (typeof REQUIRED_ON_CREATE$3)[number] | CR, typeof REFERENCES$2>;
 
 /** Resource name -> the numeric id PORTERS uses for it (docs/usage/reference/resource-api/resources-list.md). */
 declare const RESOURCE_VALUES: {
@@ -2212,7 +2232,7 @@ type ProcessCreateInput = CreateInput<typeof FIELDS$6, (typeof REQUIRED_ON_CREAT
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
 type ProcessUpdateInput = UpdateInput<typeof FIELDS$6>;
 /** The Process accessor; `C` is the declared custom-field catalog merged on. */
-type ProcessResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$6 & C, (typeof REQUIRED_ON_CREATE$1)[number], typeof REFERENCES$1>;
+type ProcessResource<C extends FieldCatalog = EmptyCatalog, CR extends keyof C = never> = Resource<typeof FIELDS$6 & C, (typeof REQUIRED_ON_CREATE$1)[number] | CR, typeof REFERENCES$1>;
 
 declare const FIELDS$5: {
     readonly P_Id: "System[Id]";
@@ -2290,7 +2310,7 @@ type ResumeCreateInput = CreateInput<typeof FIELDS$5, (typeof REQUIRED_ON_CREATE
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
 type ResumeUpdateInput = UpdateInput<typeof FIELDS$5>;
 /** The Resume accessor; `C` is the declared custom-field catalog merged on. */
-type ResumeResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$5 & C, (typeof REQUIRED_ON_CREATE)[number], typeof REFERENCES>;
+type ResumeResource<C extends FieldCatalog = EmptyCatalog, CR extends keyof C = never> = Resource<typeof FIELDS$5 & C, (typeof REQUIRED_ON_CREATE)[number] | CR, typeof REFERENCES>;
 
 /** A decoded Attachment. A field is `null` unless it was returned (see `field`). */
 type Attachment = {
@@ -2550,40 +2570,56 @@ type OptionResource = {
     search(query?: OptionSearchQuery): Promise<Option[]>;
 };
 
-/** One custom field's declared Data Type — the builder's return value. */
-type FieldDef<D extends DataType> = {
+/**
+ * One custom field's declaration — the builder's return value: its Data Type and whether
+ * `create` requires it.
+ */
+type FieldDef<D extends DataType, R extends boolean = false> = {
     readonly dataType: D;
+    /** `true` makes the field required in `create` / `createMany` input. Type-only: no runtime check. */
+    readonly required: R;
+};
+/**
+ * Options every builder method takes. `required: true` makes the field required in the
+ * `create` / `createMany` input type; leave it out (or `false`) and the field stays optional,
+ * as it always was. `update` input never requires it.
+ *
+ * @example
+ * defineFields({ candidate: (f) => ({ U_score: f.number({ required: true }) }) });
+ */
+type FieldOptions<R extends boolean = boolean> = {
+    readonly required?: R;
 };
 declare const CUSTOM_DATA_TYPES: readonly ["Number", "SinglelineText", "MultilineText", "Mail", "Telephone", "URL", "Date", "DateTime", "Age", "Option", "User", "Image", "Link"];
 type CustomDataType = (typeof CUSTOM_DATA_TYPES)[number];
 /** Builder passed to each resource declaration: one method per declarable Data Type. */
 type FieldBuilder = {
-    number(): FieldDef<"Number">;
-    singlelineText(): FieldDef<"SinglelineText">;
-    multilineText(): FieldDef<"MultilineText">;
-    mail(): FieldDef<"Mail">;
-    telephone(): FieldDef<"Telephone">;
-    url(): FieldDef<"URL">;
-    date(): FieldDef<"Date">;
-    dateTime(): FieldDef<"DateTime">;
-    age(): FieldDef<"Age">;
-    option(): FieldDef<"Option">;
-    user(): FieldDef<"User">;
+    number<R extends boolean = false>(options?: FieldOptions<R>): FieldDef<"Number", NoInfer<R>>;
+    singlelineText<R extends boolean = false>(options?: FieldOptions<R>): FieldDef<"SinglelineText", NoInfer<R>>;
+    multilineText<R extends boolean = false>(options?: FieldOptions<R>): FieldDef<"MultilineText", NoInfer<R>>;
+    mail<R extends boolean = false>(options?: FieldOptions<R>): FieldDef<"Mail", NoInfer<R>>;
+    telephone<R extends boolean = false>(options?: FieldOptions<R>): FieldDef<"Telephone", NoInfer<R>>;
+    url<R extends boolean = false>(options?: FieldOptions<R>): FieldDef<"URL", NoInfer<R>>;
+    date<R extends boolean = false>(options?: FieldOptions<R>): FieldDef<"Date", NoInfer<R>>;
+    dateTime<R extends boolean = false>(options?: FieldOptions<R>): FieldDef<"DateTime", NoInfer<R>>;
+    age<R extends boolean = false>(options?: FieldOptions<R>): FieldDef<"Age", NoInfer<R>>;
+    option<R extends boolean = false>(options?: FieldOptions<R>): FieldDef<"Option", NoInfer<R>>;
+    user<R extends boolean = false>(options?: FieldOptions<R>): FieldDef<"User", NoInfer<R>>;
     /**
      * An Image field (FT-18). Reads back `FileName` alone unless the query's `image` option asks
      * for `ContentType` / `Content`; writes the three sub-elements, checked before send.
      */
-    image(): FieldDef<"Image">;
+    image<R extends boolean = false>(options?: FieldOptions<R>): FieldDef<"Image", NoInfer<R>>;
     /**
      * A Link field (FT-20). Reads back a Contact id, a `UserRef`, or a `DepartmentRef` — whichever
      * the tenant configured, told apart by shape; writes the referenced id.
      */
-    link(): FieldDef<"Link">;
+    link<R extends boolean = false>(options?: FieldOptions<R>): FieldDef<"Link", NoInfer<R>>;
 };
 /** Data resources that accept custom fields. Master / Attachment are excluded. */
 type CustomFieldResource = "candidate" | "job" | "client" | "recruiter" | "contact" | "opportunity" | "activity" | "contract" | "sales" | "process" | "resume";
 /** One resource's custom field declarations: alias -> {@link FieldDef}. */
-type ResourceDecl = Record<string, FieldDef<DataType>>;
+type ResourceDecl = Record<string, FieldDef<DataType, boolean>>;
 /** Declaration input: per (data) resource, a builder fn returning its custom fields. */
 type FieldDecls = {
     [R in CustomFieldResource]?: (f: FieldBuilder) => ResourceDecl;
@@ -2601,6 +2637,16 @@ type CatalogOf<R extends ResourceDecl> = {
 type DeclaredCatalogsOf<D extends FieldDecls> = {
     [R in keyof D]: D[R] extends (f: FieldBuilder) => infer Out ? Out extends ResourceDecl ? CatalogOf<Out> : never : never;
 };
+type RequiredAliasesOf<R extends ResourceDecl> = {
+    [K in keyof R]: R[K]["required"] extends true ? K : never;
+}[keyof R];
+declare const requiredOnCreateBrand: unique symbol;
+/** Per declared resource, the aliases declared `required: true` — carried on the type only. */
+type DeclaredRequiredOf<D extends FieldDecls> = {
+    readonly [requiredOnCreateBrand]: {
+        [R in keyof D]: D[R] extends (f: FieldBuilder) => infer Out ? Out extends ResourceDecl ? RequiredAliasesOf<Out> : never : never;
+    };
+};
 declare const definedFieldsBrand: unique symbol;
 /** A validated set of custom field catalogs (branded — the client does not re-validate). */
 type DefinedFields<C extends DeclaredCatalogs = DeclaredCatalogs> = C & {
@@ -2608,6 +2654,14 @@ type DefinedFields<C extends DeclaredCatalogs = DeclaredCatalogs> = C & {
 };
 /** The custom catalog declared for resource `K` (or `{}` if none) — types each accessor. */
 type CustomFor<C extends DeclaredCatalogs, K extends CustomFieldResource> = K extends keyof C ? C[K] extends CustomCatalog ? C[K] : EmptyCatalog : EmptyCatalog;
+/**
+ * The aliases of resource `K` that `create` requires because the declaration said
+ * `required: true` (or `never`). Read off the phantom that {@link defineFields} puts on its
+ * result type, so a scope typed `TenantScope<typeof fields>` picks it up with no extra type argument.
+ */
+type RequiredFor<C extends DeclaredCatalogs, K extends CustomFieldResource> = C extends {
+    readonly [requiredOnCreateBrand]: infer Rq;
+} ? K extends keyof Rq ? Extract<Rq[K], keyof CustomFor<C, K>> : never : never;
 /**
  * Declare tenant-specific custom fields per data resource. This is the validation
  * boundary: it throws {@link PortersConfigError} synchronously for an unknown resource key or an
@@ -2621,7 +2675,7 @@ type CustomFor<C extends DeclaredCatalogs, K extends CustomFieldResource> = K ex
  * });
  * const t = porters.tenant(1, { fields: myFields });
  */
-declare const defineFields: <D extends FieldDecls>(decls: D) => DefinedFields<DeclaredCatalogsOf<D>>;
+declare const defineFields: <D extends FieldDecls>(decls: D) => DefinedFields<DeclaredCatalogsOf<D> & DeclaredRequiredOf<D>>;
 
 /**
  * The slice of a `tenant(id)` scope this tooling needs. Structural on purpose: pass
@@ -2673,6 +2727,13 @@ type TenantCustomCatalog = {
      * (`generateFieldDecls` has it off by default). A field PORTERS returned without a name is absent.
      */
     readonly names: Readonly<Record<string, string>>;
+    /**
+     * Bare alias -> whether the tenant marks the field required (`Field.P_Required` is `1`), for
+     * every field in {@link TenantCustomCatalog.fields}. Any other value — `0`, absent, or one
+     * PORTERS does not document — reads as `false`: a wrong `true` would make generated code demand
+     * a value the tenant does not, and the caller would get a compile error with no visible reason.
+     */
+    readonly required: Readonly<Record<string, boolean>>;
 };
 /** Options for {@link readCustomCatalog}. */
 type ReadCustomCatalogOptions = {
@@ -2767,6 +2828,20 @@ type UnverifiableResource = {
     /** Whatever Field Read rejected with (a `PortersError`, typically permission or network). */
     readonly cause: unknown;
 };
+/**
+ * Declared `required: true` while the tenant does not mark the field required, or the reverse.
+ * Harmless either way — reads and writes work — so it does not clear {@link FieldVerification.ok}.
+ * `declared: true, tenant: false` is a declaration stricter than the tenant (perhaps on purpose);
+ * `declared: false, tenant: true` means `create` will not stop a missing value at compile time.
+ */
+type RequiredMismatch = {
+    readonly resource: CustomFieldResource;
+    readonly alias: string;
+    /** Whether the declaration says `required: true`. */
+    readonly declared: boolean;
+    /** Whether the tenant marks the field required (`Field.P_Required` is `1`). */
+    readonly tenant: boolean;
+};
 /** A tenant field that exists but no declaration can express (carried through from the catalog). */
 type UndeclarableTenantField = UndeclarableField & {
     readonly resource: CustomFieldResource;
@@ -2778,8 +2853,8 @@ type FieldVerification = {
      * {@link FieldVerification.missing}, {@link FieldVerification.typeMismatch} or
      * {@link FieldVerification.unverifiable}.
      *
-     * `undeclared` and `undeclarable` do **not** clear this flag: neither breaks anything, they are
-     * there to be read.
+     * `undeclared`, `undeclarable` and `requiredMismatch` do **not** clear this flag: none of them
+     * breaks anything, they are there to be read.
      */
     readonly ok: boolean;
     readonly missing: readonly MissingField[];
@@ -2787,6 +2862,7 @@ type FieldVerification = {
     readonly undeclared: readonly UndeclaredField[];
     readonly unverifiable: readonly UnverifiableResource[];
     readonly undeclarable: readonly UndeclarableTenantField[];
+    readonly requiredMismatch: readonly RequiredMismatch[];
 };
 /** Options for {@link verifyFields}. */
 type VerifyFieldsOptions = {
@@ -2820,7 +2896,7 @@ declare const verifyFields: (source: FieldCatalogSource, fields: DeclaredCatalog
  * resource that could not be read**. That last one is deliberate: "we could not check" is not
  * "everything is fine", and passing it silently would defeat the point of asking.
  *
- * `undeclared` / `undeclarable` never throw — nothing is broken by either.
+ * `undeclared` / `undeclarable` / `requiredMismatch` never throw — nothing is broken by any of them.
  *
  * @example
  * assertFieldsMatch(await verifyFields(porters.tenant(1), myFields));
@@ -2862,10 +2938,21 @@ type PortersClientOptions = {
     appId?: string;
     appSecret?: string;
     scopes?: Scope[];
-    /** Custom auth strategy; defaults to the transparent code_direct strategy. */
-    auth?: TokenProvider;
-    /** Token persistence; defaults to in-memory. */
+    /**
+     * Where tokens come from. Leave it out for the built-in flow (`code_direct` with `appId` /
+     * `appSecret`); pass one to obtain tokens another way — for example from a central service that
+     * holds the App Secret. Either way the client caches, renews before expiry, retries once on an
+     * expired token, and saves to `tokenStore`.
+     */
+    tokenProvider?: TokenProvider;
+    /** Token persistence, used with every token provider; defaults to in-memory. */
     tokenStore?: TokenStore;
+    /**
+     * **Not a client option any more.** Pass a `tokenProvider` (`{ acquire, refresh?, exchange? }`)
+     * instead; the client manages caching and renewal for it. Typed `never` so a leftover `auth`
+     * fails to compile; at runtime the constructor rejects it with {@link PortersConfigError}.
+     */
+    auth?: never;
     /** Injectable HTTP transport; defaults to a fetch-based transport. */
     transport?: Transport;
     /**
@@ -2913,22 +3000,22 @@ type TenantOptions<C extends DeclaredCatalogs = EmptyCatalog> = {
  * (no nesting) are deliberately absent: none of them takes a partition.
  */
 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 recruiter: RecruiterResource<CustomFor<C, "recruiter">>;
-    readonly contact: ContactResource<CustomFor<C, "contact">>;
-    readonly opportunity: OpportunityResource<CustomFor<C, "opportunity">>;
-    readonly activity: ActivityResource<CustomFor<C, "activity">>;
-    readonly contract: ContractResource<CustomFor<C, "contract">>;
-    readonly sales: SalesResource<CustomFor<C, "sales">>;
+    readonly candidate: CandidateResource<CustomFor<C, "candidate">, RequiredFor<C, "candidate">>;
+    readonly job: JobResource<CustomFor<C, "job">, RequiredFor<C, "job">>;
+    readonly client: ClientResource<CustomFor<C, "client">, RequiredFor<C, "client">>;
+    readonly recruiter: RecruiterResource<CustomFor<C, "recruiter">, RequiredFor<C, "recruiter">>;
+    readonly contact: ContactResource<CustomFor<C, "contact">, RequiredFor<C, "contact">>;
+    readonly opportunity: OpportunityResource<CustomFor<C, "opportunity">, RequiredFor<C, "opportunity">>;
+    readonly activity: ActivityResource<CustomFor<C, "activity">, RequiredFor<C, "activity">>;
+    readonly contract: ContractResource<CustomFor<C, "contract">, RequiredFor<C, "contract">>;
+    readonly sales: SalesResource<CustomFor<C, "sales">, RequiredFor<C, "sales">>;
     /**
      * Phase history, reached through the resource it belongs to: `t.phase.of("client")`.
      * PORTERS requires that `resource` on every Phase call, so it is bound once.
      */
     readonly phase: PhaseAccessor;
-    readonly process: ProcessResource<CustomFor<C, "process">>;
-    readonly resume: ResumeResource<CustomFor<C, "resume">>;
+    readonly process: ProcessResource<CustomFor<C, "process">, RequiredFor<C, "process">>;
+    readonly resume: ResumeResource<CustomFor<C, "resume">, RequiredFor<C, "resume">>;
     /**
      * Attachments, reached through the resource they belong to: `t.attachment.of("resume")`.
      * PORTERS requires that `resource` on every Attachment Read, and the same value fills the
@@ -3104,4 +3191,4 @@ declare const decodeTimeOfDay: (iso: string) => string;
  */
 declare const encodeTimeOfDay: (time: string) => string;
 
-export { type Activity, type ActivityCreateInput, type ActivityPage, type ActivityResource, type ActivitySearchQuery, type ActivityUpdateInput, type Attachment, type AttachmentAccessor, type AttachmentCreate, type AttachmentPage, type AttachmentResource, type AttachmentSearchQuery, type AttachmentUpdate, type AttachmentWalkQuery, 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 Contact, type ContactCreateInput, type ContactPage, type ContactResource, type ContactSearchQuery, type ContactUpdateInput, type Contract, type ContractCreateInput, type ContractPage, type ContractResource, type ContractSearchQuery, type ContractUpdateInput, type CustomDataType, type CustomFieldResource, type CustomFor, type DeclaredCatalogs, type DefinedFields, type Department, type DepartmentPage, type DepartmentRef, type DepartmentResource, type DepartmentSearchQuery, type ErrorCategory, type Expand, type ExpandedReadRecord, type FetchTransportOptions, type Field, type FieldAccessor, type FieldBuilder, type FieldCatalogSource, type FieldDecls, type FieldDef, type FieldPage, type FieldResource, type FieldSearchQuery, type FieldTypeMismatch, type FieldValue, type FieldVerification, type GenerateFieldDeclsOptions, type GetAccessTokenOptions, type ImageContentType, type ImageOption, type ImageReadRecord, type ImageSelectedValue, type ImageSubField, type ImageValue, type ImageWriteValue, type ItemState, type Job, type JobCreateInput, type JobPage, type JobResource, type JobSearchQuery, type JobUpdateInput, type LinkValue, type MissingField, type MockHandler, type MockReply, type MockTransportOptions, type Opportunity, type OpportunityCreateInput, type OpportunityPage, type OpportunityResource, type OpportunitySearchQuery, type OpportunityUpdateInput, type Option, type OptionResource, type OptionSearchQuery, type Order, type Partition, type PartitionId, type PartitionPage, type PartitionResource, type PartitionSearchQuery, type Phase, type PhaseAccessor, type PhaseCreateInput, type PhasePage, type PhaseResource, type PhaseSearchQuery, type PhaseUpdateInput, 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 ReadCustomCatalogOptions, type ReadFieldAlias, type Recruiter, type RecruiterCreateInput, type RecruiterPage, type RecruiterResource, type RecruiterSearchQuery, type RecruiterUpdateInput, type ReferenceMap, type ReferenceRecord, type ResourceName, type ResourcePageOf, type ResourceType, type Resume, type ResumeCreateInput, type ResumePage, type ResumeResource, type ResumeSearchQuery, type ResumeUpdateInput, type RevokeUrlOptions, type Sales, type SalesCreateInput, type SalesPage, type SalesResource, type SalesSearchQuery, type SalesUpdateInput, type Scheme, type Scope, type SearchQuery, type StoredTokens, type TenantCustomCatalog, type TenantOptions, type TenantScope, type Throttle, type ThrottleOptions, type TokenProvider, type TokenStore, type Transport, type TransportRequest, type TransportResponse, type UndeclarableField, type UndeclarableReason, type UndeclarableTenantField, type UndeclaredField, type UnverifiableResource, type User, type UserPage, type UserRef, type UserResource, type UserSearchQuery, type VerifyFieldsOptions, assertFieldsMatch, base64ToBytes, bytesToBase64, createFetchTransport, createMockTransport, createThrottle, decodeTimeOfDay, defineFields, encodeTimeOfDay, generateFieldDecls, rawValue, readCustomCatalog, resourceNameOf, resourceValueOf, verifyFields };
+export { type Activity, type ActivityCreateInput, type ActivityPage, type ActivityResource, type ActivitySearchQuery, type ActivityUpdateInput, type Attachment, type AttachmentAccessor, type AttachmentCreate, type AttachmentPage, type AttachmentResource, type AttachmentSearchQuery, type AttachmentUpdate, type AttachmentWalkQuery, 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 Contact, type ContactCreateInput, type ContactPage, type ContactResource, type ContactSearchQuery, type ContactUpdateInput, type Contract, type ContractCreateInput, type ContractPage, type ContractResource, type ContractSearchQuery, type ContractUpdateInput, type CustomDataType, type CustomFieldResource, type CustomFor, type DeclaredCatalogs, type DeclaredRequiredOf, type DefinedFields, type Department, type DepartmentPage, type DepartmentRef, type DepartmentResource, type DepartmentSearchQuery, type ErrorCategory, type Expand, type ExpandedReadRecord, type FetchTransportOptions, type Field, type FieldAccessor, type FieldBuilder, type FieldCatalogSource, type FieldDecls, type FieldDef, type FieldOptions, type FieldPage, type FieldResource, type FieldSearchQuery, type FieldTypeMismatch, type FieldValue, type FieldVerification, type GenerateFieldDeclsOptions, type ImageContentType, type ImageOption, type ImageReadRecord, type ImageSelectedValue, type ImageSubField, type ImageValue, type ImageWriteValue, type IssuedToken, type ItemState, type Job, type JobCreateInput, type JobPage, type JobResource, type JobSearchQuery, type JobUpdateInput, type LinkValue, type MissingField, type MockHandler, type MockReply, type MockTransportOptions, type Opportunity, type OpportunityCreateInput, type OpportunityPage, type OpportunityResource, type OpportunitySearchQuery, type OpportunityUpdateInput, type Option, type OptionResource, type OptionSearchQuery, type Order, type Partition, type PartitionId, type PartitionPage, type PartitionResource, type PartitionSearchQuery, type Phase, type PhaseAccessor, type PhaseCreateInput, type PhasePage, type PhaseResource, type PhaseSearchQuery, type PhaseUpdateInput, 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 ReadCustomCatalogOptions, type ReadFieldAlias, type Recruiter, type RecruiterCreateInput, type RecruiterPage, type RecruiterResource, type RecruiterSearchQuery, type RecruiterUpdateInput, type ReferenceMap, type ReferenceRecord, type RequiredFor, type RequiredMismatch, type ResourceName, type ResourcePageOf, type ResourceType, type Resume, type ResumeCreateInput, type ResumePage, type ResumeResource, type ResumeSearchQuery, type ResumeUpdateInput, type RevokeUrlOptions, type Sales, type SalesCreateInput, type SalesPage, type SalesResource, type SalesSearchQuery, type SalesUpdateInput, type Scheme, type Scope, type SearchQuery, type StoredTokens, type TenantCustomCatalog, type TenantOptions, type TenantScope, type Throttle, type ThrottleOptions, type TokenProvider, type TokenStore, type Transport, type TransportRequest, type TransportResponse, type UndeclarableField, type UndeclarableReason, type UndeclarableTenantField, type UndeclaredField, type UnverifiableResource, type User, type UserPage, type UserRef, type UserResource, type UserSearchQuery, type VerifyFieldsOptions, assertFieldsMatch, base64ToBytes, bytesToBase64, createFetchTransport, createMockTransport, createThrottle, decodeTimeOfDay, defineFields, encodeTimeOfDay, generateFieldDecls, rawValue, readCustomCatalog, resourceNameOf, resourceValueOf, verifyFields };