@joymerrevent/porters-connect 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -5,6 +5,58 @@
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-09-25
+
+**設定の誤りを黙って通さないようにし、トークンを期限つきで取り出せるようにした版**です。**破壊的変更を 2 つ**含みます
+（定義していないオプションの拒否と、`porters.auth.getToken()` の戻り値）。あわせて、トークンの保存と中央のサービスからの
+受け取りの実践例を足し、README と目次を読みやすく直しました。
+
+### Changed
+
+- **（破壊的）`new PortersClient(options)` と `porters.tenant(id, options)` は、定義していないオプションのキーを渡すと
+  `PortersConfigError`（`category: "config"`）になります**（[ADR-0092][adr92]）。これまでは打ち間違い（`hostName` など）や
+  存在しないオプションを黙って無視し、誤った設定のまま動いていました。
+
+  ```ts
+  new PortersClient({ hostname, appId, appSecret, hostName: "x" });
+  // PortersConfigError: PortersClient: unknown option "hostName"
+  //   hint: Valid options: hostname, port, scheme, appId, appSecret, scopes, tokenProvider, tokenStore, transport, throttle.
+  ```
+
+  - 値が `undefined` のキーは未指定と同じ扱いです（設定をスプレッドで組み立てると混ざりやすいため）。
+  - **アプリの設定オブジェクトを丸ごと渡している場合は、使うキーだけを取り出して渡してください。**
+  - `tenant(id, options)` に渡せるのは `fields` だけです。
+  - `PortersClientOptions` の型から、使えない項目だった `auth` と `fields` を外しました。
+
+- **（破壊的）`porters.auth.getToken()` は、Access Token の文字列ではなく `{ token, expiresAt? }`（`IssuedToken`）を
+  返すようになりました**（[ADR-0093][adr93]）。
+
+  ```ts
+  // 変更前
+  const token = await porters.auth.getToken();
+  // 変更後
+  const { token, expiresAt } = await porters.auth.getToken();
+  ```
+
+  - 返すのはリソースの呼び出しに使うのと同じトークンで、期限が近ければ取り直してから返します。`expiresAt` は
+    1970-01-01 からのミリ秒で、取り方が期限を返さなかったときは省かれます。
+  - 中央のサービスが各アプリの `tokenProvider` にトークンを渡すとき、期限もそのまま渡せます。アプリのクライアントは
+    期限切れで失敗する前に取り直せます。
+  - Refresh Token はこれまでどおり返しません。
+
+- **使い方ドキュメントに実践例を 2 本足しました**:
+  [トークンを DB に保存する][recipe-token-store-db]（`tokenStore` を Drizzle ORM と PostgreSQL で組む）と、
+  [中央のサービスからトークンを受け取る][recipe-central-token-service]（App Secret を中央だけに置き、各アプリは
+  `tokenProvider` で受け取る）。
+
+- **README と目次を見直しました**。README の「リソースと操作」の節を外して入口に絞り、見出し「最短で動かす」を
+  「クイックスタート」に、各章の説明を概要の要約にしました。使い方ドキュメントの章の名前を「主題別」から
+  「ガイド」に、「リソース別」から「リソース」に改めました（ページの場所は変わりません）。
+  `tokenProvider` に渡す関数が、取るのに要るもの（App Secret など）を自分で持つことも書き足しました。
+
+- 内部の検査を変えました（利用者への影響はありません）。PR のミューテーションテストは変更したファイルだけに掛け、
+  `main` への PR は必ず全体を検査します。
+
 ## [0.24.0] - 2026-09-24
 
 **トークンの取り方と置き場所を別々に渡せるようにした版**です。**破壊的変更を 2 つ**含みます
@@ -1456,7 +1508,8 @@ 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.24.0...HEAD
+[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.25.0...HEAD
+[0.25.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.24.0...v0.25.0
 [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
@@ -1502,4 +1555,8 @@ Attachment）あるのに、受け口の形が 3 つとも違っていました
 [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
+[adr92]: docs/adr/0092-reject-unknown-options.md
+[adr93]: docs/adr/0093-get-token-with-expiry.md
+[recipe-token-store-db]: docs/usage/recipes/token-store-db.md
+[recipe-central-token-service]: docs/usage/recipes/central-token-service.md
 [troubleshooting]: docs/usage/reference/troubleshooting.md

package/README.md

@@ -9,35 +9,39 @@ PORTERS Connect API（旧 HRBC）を **TypeScript から型安全・簡単に**
 > これは**非公式**ライブラリです。ポーターズ株式会社とは無関係で、公式ロゴ・商標は使用していません。
 > 利用には **PORTERS の契約 ＋ Connect API オプション契約**が必要です（ホスト名・App ID/Secret は契約時に通知されます）。
 
-XML レスポンスを型付きオブジェクトに変換し、独自仕様の OAuth・レート制御・エラー整理を内側に隠します。
+PORTERS が返す XML は、型の付いたオブジェクトに変換して返します。PORTERS 独自の OAuth、上限を守るための制御、
+エラーの分類はライブラリが受け持ちます。
 
 ---
 
 ## 特徴
 
-- **型安全**：リソース・項目の値を型で表現。`any` を使いません。
-- **XML を外に出さない**：返り値は型付きオブジェクト、入力もふつうの JS の値。
-- **独自 OAuth を意識させない**：`code_direct` によるトークン取得・キャッシュ・更新を自動化。
-- **上限を守る**：スロットリング・リトライ（指数バックオフ）・リクエストの長さの検査を内蔵。
-- **日時は ISO 8601（UTC）に正規化**。業務タイムゾーン変換はしません（利用側の責務）。
-- **PORTERS の全リソースに対応**：データ系 13 種（Phase・Attachment を含む）＋ マスタ系 5 種（読み取り専用）。
+- **型安全**：リソースと項目の値に型が付きます。`any` は使いません。
+- **XML を扱わなくてよい**：戻り値は型の付いたオブジェクトで、渡す値もふつうの JavaScript の値です。
+- **OAuth の手続きを自動で行う**：`code_direct` でのトークンの取得・キャッシュ・更新をライブラリが行います。
+- **上限を守る**：スロットリング、リトライ（指数バックオフ）、リクエストの長さの検査を備えています。
+- **日時は ISO 8601（UTC）でやり取りする**：JST などへの変換はしません（利用側で行います）。
+- **PORTERS の全リソースに対応**：マスタ系 5 種（読み取り専用）＋ データ系 13 種（Phase・Attachment を含む）。
+  一覧と呼べるメソッドは[リソースと操作][docs-resources]にあります。
 
 ## 前提
 
-繋ぐ前に、**PORTERS 側で 4 つ**が要ります。揃っていないと PORTERS を呼べません。
+使い始める前に、次の **4 つ**を済ませておく必要があります。揃っていないと PORTERS を呼べません。
 
 1. **PORTERS 契約 ＋ Connect API オプション契約**（オプションは別契約）。
-2. **API アプリの登録**。ここで Redirect URL を決め、**ホスト名・App ID・App Secret** が
+2. **PORTERS への API アプリの登録**。ここで Redirect URL を決め、**ホスト名・App ID・App Secret** が
    通知されます（いずれも機密情報なので、コードに直接書かず環境変数で渡します）。
-3. **初回のみブラウザで権限付与**（人手・Company DB ごとに 1 回）。以降はライブラリが
-   `code_direct`（サーバ間）で無人運用します。
-4. **付与するスコープ**の決定（リソース別に `_r` / `_w`。Read でも複数要ることがあります）。
+3. **初回だけ、ブラウザで権限を付与する**（人の操作が要ります。Company DB ごとに 1 回）。2 回目以降は、ライブラリが
+   `code_direct`（サーバ間）で人の操作なしにトークンを取ります。
+4. **付与するスコープを決める**（リソースごとに読み `_r` / 書き `_w`。読み取りだけでも複数のスコープが要ることがあります）。
 
-揃えかたは[始める前に][s-prereq]に、権限付与の手順は[認証を通して、疎通を確認する][s-auth]に
-あります。実行環境は **Node.js 22.12 以上**で、型定義は同梱です（型を読むには **TypeScript 5.4 以上**が要ります）。ビルド済みの JavaScript ファイルは ESM（`import`）の 1 つですが、
-CJS（`require`）からも `require("@joymerrevent/porters-connect")` で読めます（[CJS から使う][s-cjs]）。
+揃え方は[始める前に][s-prereq]に、権限付与の手順は[認証を通して、疎通を確認する][s-auth]にあります。
 
-契約や権限付与を**待っている間**も、PORTERS に繋がずにコードとテストは書けます
+実行環境は **Node.js 22.12 以上**です。型定義は同梱していて、型を読むには **TypeScript 5.4 以上**が要ります。
+配布しているのは ESM（`import`）のファイル 1 つですが、CJS（`require`）からも
+`require("@joymerrevent/porters-connect")` で読み込めます（[CJS から使う][s-cjs]）。
+
+契約や権限付与を**待っている間**も、PORTERS に接続せずにコードとテストを書けます
 （[契約なしでテストする][test-without-contract]）。
 
 ## インストール
@@ -48,7 +52,7 @@ npm i @joymerrevent/porters-connect
 # yarn add @joymerrevent/porters-connect
 ```
 
-## 最短で動かす
+## クイックスタート
 
 ```ts
 import { PortersClient } from "@joymerrevent/porters-connect";
@@ -59,7 +63,7 @@ const porters = new PortersClient({
   appSecret: process.env.PORTERS_APP_SECRET ?? "",
 });
 
-// partition（Company DB）は tenant(id) で指定する（既定の Partition は無い）。単一テナントでも同じ書き方
+// Partition（Company DB）は tenant(id) で指定する（既定の Partition は無い）。テナントが 1 つでも同じ書き方
 const t = porters.tenant(456);
 
 const page = await t.candidate.search({
@@ -72,74 +76,59 @@ const page = await t.candidate.search({
 console.log(page.total, page.items[0]?.P_Name);
 ```
 
-続きは[導入][s-prereq]（6 ページ）へ。準備・認証・読み取り・書き込み・本番に出す前の確認まで順に進みます。
-
-## リソースと操作
-
-| アクセサ        | リソース       | アクセサ       | リソース     |
-| --------------- | -------------- | -------------- | ------------ |
-| `t.candidate`   | 個人連絡先     | `t.contract`   | 契約         |
-| `t.job`         | JOB            | `t.sales`      | 成約・売上   |
-| `t.client`      | 企業           | `t.process`    | 選考プロセス |
-| `t.recruiter`   | 企業担当者     | `t.resume`     | レジュメ     |
-| `t.contact`     | コンタクト     | `t.attachment` | 添付ファイル |
-| `t.opportunity` | 商談管理       | `t.phase`      | フェーズ履歴 |
-| `t.activity`    | アクティビティ |                |              |
-
-マスタ系は `porters.partition` / `t.user` / `t.department` / `t.field` / `t.option` の 5 種（読み取り専用）。
-
-**どのメソッドが呼べるかはリソースごとに違います**（`searchAll` が無いもの、先に `of("candidate")` のように
-対象リソースを指定するもの（Field・Phase・Attachment）があります）。一覧は[リソースと操作][docs-resources]、引数・戻り値・項目の一覧は
-[API リファレンス][api-ref]が正確な定義です。
+README で説明するのはここまでです。認証の準備・書き込み・エラーの扱いなど、使い方の全体は
+[docs/usage][docs-index] の目次から読めます<!-- 根拠: ADR-0070（README は入口に絞る） -->。はじめての人は[導入][s-prereq]（6 ページ）から順に進んでください。
 
 ## ドキュメント
 
 **[docs/usage][docs-index] が目次**です。7 つの章に分かれていて、順に読むのは導入だけです。
 
-| 章               | 何が書いてあるか                                                                            |
-| ---------------- | ------------------------------------------------------------------------------------------- |
-| **導入**         | 順に読む 6 ページ。準備 → インストール → 認証と疎通 → 読み → 書き → 本番前                  |
-| **主題別**       | 認証・検索・書き込み・カスタム項目・上限……の 11 主題を、考え方から細かい規則まで 1 ページで |
-| **クライアント** | `PortersClient`・`auth`・`tenant(id)` のスコープ。構築オプションと呼べるメソッド            |
-| **リソース別**   | 18 リソースを 1 ページずつ。呼べるメソッド・固有の注意・必須項目・型                        |
-| **関数**         | `import` して呼ぶ関数を用途別に。宣言と突合・上限と接続・値の変換                           |
-| **実践例**       | 毎日の差分同期・複数テナントなど、用途に沿った組み立て                                      |
-| **リファレンス** | [公開 API リファレンス][api-ref]（JSDoc から生成）と [PORTERS API の事実][ref]              |
+| 章               | 概要                                                                                                                                                             |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **導入**         | PORTERS への接続から、データの読み書き、本番での運用までを、6 ページで順に説明します                                                                             |
+| **ガイド**       | Partition・検索・書き込み・認証・上限など、PORTERS を使ううえで欠かせない事柄を 1 ページずつ説明します。PORTERS 側の前提と、ライブラリが受け持つ範囲が分かります |
+| **クライアント** | クライアントの作り方と、クライアントから呼び出せる機能をまとめています                                                                                           |
+| **リソース**     | 18 のリソースごとに、使えるメソッド・注意点・新規作成の必須項目をまとめています                                                                                  |
+| **関数**         | `import` して使う関数ごとに、使い方と失敗したときの扱いをまとめています                                                                                          |
+| **実践例**       | 毎日の差分同期や複数テナントなど、よくある用途ごとに、機能の組み合わせ方をサンプルコードで示します                                                               |
+| **リファレンス** | 型やメソッドの正確な定義（[公開 API リファレンス][api-ref]）と、PORTERS 側の仕様（[PORTERS API の事実][ref]）をまとめています                                    |
 
-目次の末尾に「〜したい → 読む場所」の索引表があります。
+目次の末尾の「目的から探す」から、やりたいことに合うページへ直接進めます。
 
 ## PORTERS 固有の注意
 
-このライブラリを使ううえで、**PORTERS 側の前提**として先に知っておくと迷いません。詳しくは
-それぞれの主題ページの「まず知ること」にあります。
+PORTERS 側の仕様で、使い始める前に知っておきたいものです。詳しくは、それぞれのガイドのページの「まず知ること」に
+あります。
 
-- **削除 API が存在しない**。`delete()` は型の上でも用意していません（[削除と削除済みデータ][c-no-delete]）。
-- **日時は UTC 前提**。ISO 8601（`…Z`）で入出力し、JST 等への変換はしません（[日時と時分型][c-datetime]）。
-- **データは Partition に分かれる**。`tenant(id)` で毎回指定します（[Partition とテナントスコープ][c-partition]）。
-- **上限がある**。リクエスト長 約 15000 文字・1 リクエスト 200 件・1 分あたり Read 2000 / Write 500 は
-  ライブラリが守りますが、**月 15 万アクセスは契約条件**で利用側の運用責務です（[上限とレート][c-limits]）。
-- **ホスト名は非公開**。`PORTERS_HOST` で受け取り、ハードコードしません。
+- **PORTERS には削除の API がありません**。このライブラリにも `delete()` はありません（[削除と削除済みデータ][c-no-delete]）。
+- **日時は UTC です**。ISO 8601（`…Z`）で受け渡しし、JST などへの変換はしません（[日時と時分型][c-datetime]）。
+- **データは Partition（Company DB）ごとに分かれています**。`tenant(id)` で Partition を指定してから読み書きします
+  （[Partition とテナントスコープ][c-partition]）。
+- **上限があります**。リクエストの長さ（約 15000 文字）・1 リクエスト 200 件・1 分あたり Read 2000 / Write 500 は
+  ライブラリが守ります。**月 15 万アクセスは契約の条件**で、数えて守るのは利用側です（[上限とレート][c-limits]）。
+- **ホスト名は契約時に通知されます**。環境変数（`PORTERS_HOST` など）で渡し、コードに直接書かないでください。
 
 ## 対応バージョン
 
-- **互換性の基準は Connect API Version 2**：`X-P-ConnectAPI-Version: 2` を既定で送信し、**v2 を動作の前提**とします（担当者型・部署型の参照項目（Link）などは v2 が必要）。互換性はこの **API version** で明示します。
-- **PORTERS 製品 8.x / 9.x は参考**：v2 が提供される製品世代です（個別マイナーの動作保証はしません）。**正しい情報の出どころは [PORTERS API の事実][ref]**（PORTERS の公式ドキュメントに基づく）。
+- **Connect API Version 2 を前提にしています**。リクエストには `X-P-ConnectAPI-Version: 2` を付けて送ります
+  （担当者型・部署型の参照項目（Link）などは v2 が必要です）。互換性は、この Connect API のバージョンで示します。
+- **PORTERS の製品バージョン 8.x / 9.x は参考です**。どちらも v2 を提供している世代ですが、マイナーバージョンごとの動作は
+  保証しません。PORTERS 側の仕様は [PORTERS API の事実][ref]（PORTERS の公式ドキュメントに基づく）にまとめています。
 
 ## リンク
 
-**この README は「最短で動かす」ところまで**です。全体は目次から読めます<!-- 根拠: ADR-0070 -->。
-
 - 利用者向け：[docs/usage][docs-index]（目次）／[公開 API リファレンス][api-ref]／[PORTERS API の事実][ref]
 - 開発・保守：[docs/README.md][docs-readme]（ADR（設計判断の記録）・基本設計・ロードマップ・台帳）
 - 提供元：[Joymerrevent][joymerrevent]
 
 ## コントリビュート / セキュリティ
 
-- バグ報告・要望・質問は [Issues][issues] へ（外部からの提案は Issue 経由・PR 作成はコラボレーター限定）。詳しくは [CONTRIBUTING][contributing]。
+- バグ報告・要望・質問は [Issues][issues] へお願いします。外部の方からの提案は Issue で受け付けていて、PR を作れるのは
+  コラボレーターだけです。詳しくは [CONTRIBUTING][contributing] にあります。
 - 脆弱性は公開 Issue ではなく [セキュリティポリシー][security] の手順で**非公開**で報告してください。
-- 行動規範：[Contributor Covenant][coc]。
+- 行動規範は [Contributor Covenant][coc] です。
 
-> 念のため：本ライブラリは**非公式**です。PORTERS 製品・Connect API 本体の不具合や要望は PORTERS 公式へお願いします。
+> このライブラリは**非公式**です。PORTERS の製品や Connect API そのものの不具合・要望は、PORTERS の公式窓口へお問い合わせください。
 
 ## ライセンス
 

package/dist/index.d.cts

@@ -190,8 +190,14 @@ type AuthApi = {
     clearTokens(): Promise<void>;
     /** Acquire a token now (startup fail-fast / warm-up); throws if auth is unavailable. */
     ensureAuthenticated(): Promise<void>;
-    /** Return the current valid Access Token (debug). The Refresh Token is never exposed. */
-    getToken(): Promise<string>;
+    /**
+     * The Access Token the client currently uses, with its expiry — renewed first when it is within
+     * the refresh margin, exactly as a request would. `expiresAt` is epoch milliseconds, or absent
+     * when the token provider did not report one. Use it to hand the token to another process (for
+     * example, a central service answering its apps' `tokenProvider.acquire`). The Refresh Token is
+     * never exposed.
+     */
+    getToken(): Promise<IssuedToken>;
 };
 
 type DataType = "System[Id]" | "Number" | "DateTime" | "System[DateTime]" | "Date" | "Age" | "SinglelineText" | "MultilineText" | "Mail" | "Telephone" | "URL" | "User" | "Option" | "System[Reference]" | "System[Department]" | "Image" | "Link";
@@ -2947,12 +2953,6 @@ type PortersClientOptions = {
     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;
     /**
@@ -2964,14 +2964,6 @@ type PortersClientOptions = {
      * library leaves that to you. `createThrottle()` builds the default implementation.
      */
     throttle?: Throttle;
-    /**
-     * **Not a client option any more.** Custom fields belong to a partition, so the
-     * declaration goes to {@link PortersClient.tenant} as `tenant(id, { fields })`. Typed `never`
-     * so a configuration object that still carries the pre-0.21 `fields` fails to compile even when
-     * it is not a fresh literal; at runtime the constructor rejects it with {@link PortersConfigError}
-     * rather than silently dropping the declaration (the same fail-closed stance as `hostname`).
-     */
-    fields?: never;
 };
 /**
  * Options for {@link PortersClient.tenant}. `C` is inferred from `fields`.

package/dist/index.d.ts

@@ -190,8 +190,14 @@ type AuthApi = {
     clearTokens(): Promise<void>;
     /** Acquire a token now (startup fail-fast / warm-up); throws if auth is unavailable. */
     ensureAuthenticated(): Promise<void>;
-    /** Return the current valid Access Token (debug). The Refresh Token is never exposed. */
-    getToken(): Promise<string>;
+    /**
+     * The Access Token the client currently uses, with its expiry — renewed first when it is within
+     * the refresh margin, exactly as a request would. `expiresAt` is epoch milliseconds, or absent
+     * when the token provider did not report one. Use it to hand the token to another process (for
+     * example, a central service answering its apps' `tokenProvider.acquire`). The Refresh Token is
+     * never exposed.
+     */
+    getToken(): Promise<IssuedToken>;
 };
 
 type DataType = "System[Id]" | "Number" | "DateTime" | "System[DateTime]" | "Date" | "Age" | "SinglelineText" | "MultilineText" | "Mail" | "Telephone" | "URL" | "User" | "Option" | "System[Reference]" | "System[Department]" | "Image" | "Link";
@@ -2947,12 +2953,6 @@ type PortersClientOptions = {
     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;
     /**
@@ -2964,14 +2964,6 @@ type PortersClientOptions = {
      * library leaves that to you. `createThrottle()` builds the default implementation.
      */
     throttle?: Throttle;
-    /**
-     * **Not a client option any more.** Custom fields belong to a partition, so the
-     * declaration goes to {@link PortersClient.tenant} as `tenant(id, { fields })`. Typed `never`
-     * so a configuration object that still carries the pre-0.21 `fields` fails to compile even when
-     * it is not a fresh literal; at runtime the constructor rejects it with {@link PortersConfigError}
-     * rather than silently dropping the declaration (the same fail-closed stance as `hostname`).
-     */
-    fields?: never;
 };
 /**
  * Options for {@link PortersClient.tenant}. `C` is inferred from `fields`.

package/dist/index.js

@@ -725,6 +725,8 @@ var createTokenManager = (opts) => {
   };
   return {
     getAccessToken: async (o) => (await ensure(o?.forceRefresh ?? false)).accessToken.token,
+    // 写しを返す: 受け取った側が書き換えても、キャッシュの値（リクエストに使う値）は変わらない。
+    getIssuedToken: async () => ({ ...(await ensure(false)).accessToken }),
     cache: async (tokens) => {
       await save(requireTokens(tokens, "exchange"));
     },
@@ -792,7 +794,7 @@ var createAuthApi = (opts) => {
     },
     // `async` so a provider that throws synchronously still reaches the caller as a
     // rejection — a Promise-returning method never throws (ADR-0046).
-    getToken: async () => opts.manager.getAccessToken()
+    getToken: async () => opts.manager.getIssuedToken()
   };
 };
 
@@ -2703,6 +2705,34 @@ var createOptionResource = (deps) => {
 };
 
 // src/client.ts
+var CLIENT_OPTION_KEYS = {
+  hostname: true,
+  port: true,
+  scheme: true,
+  appId: true,
+  appSecret: true,
+  scopes: true,
+  tokenProvider: true,
+  tokenStore: true,
+  transport: true,
+  throttle: true
+};
+var TENANT_OPTION_KEYS = {
+  fields: true
+};
+var rejectUnknownKeys = (where, options, allowed) => {
+  const unknown = Object.entries(options).filter(
+    ([key, value]) => !Object.hasOwn(allowed, key) && value !== void 0
+  ).map(([key]) => JSON.stringify(key));
+  if (unknown.length === 0) return;
+  throw new PortersConfigError(
+    `${where}: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")}`,
+    {
+      category: "config",
+      hint: `Valid options: ${Object.keys(allowed).join(", ")}.`
+    }
+  );
+};
 var validateTokenProvider = (provider) => {
   if (provider === void 0) return;
   const p = provider;
@@ -2763,24 +2793,7 @@ var PortersClient = class {
   tenant;
   #accessPoint;
   constructor(options) {
-    if (options.fields !== void 0) {
-      throw new PortersConfigError(
-        'PortersClient: "fields" is not a client option \u2014 custom fields belong to a partition',
-        {
-          category: "config",
-          hint: "Declare them where you bind the partition: porters.tenant(id, { fields })"
-        }
-      );
-    }
-    if (options.auth !== void 0) {
-      throw new PortersConfigError(
-        'PortersClient: "auth" is not a client option \u2014 pass a tokenProvider instead',
-        {
-          category: "config",
-          hint: "Replace auth: { getAccessToken } with tokenProvider: { acquire: async () => ({ accessToken: { token } }) }. The client caches and renews the token for you."
-        }
-      );
-    }
+    rejectUnknownKeys("PortersClient", options, CLIENT_OPTION_KEYS);
     validateTokenProvider(options.tokenProvider);
     const accessPoint = {
       hostname: options.hostname,
@@ -2818,6 +2831,7 @@ var PortersClient = class {
     });
     this.#accessPoint = accessPoint;
     const buildScope = (partition, scope = {}) => {
+      rejectUnknownKeys("tenant", scope, TENANT_OPTION_KEYS);
       const customFor = (key) => scope.fields?.[key] ?? {};
       const deps = { requester, accessPoint, partition };
       return {