@lunch-money/developer-docs 2.11.2-preview.6 → 2.11.2-preview.8

package/docs/oauth/sample-applications.md

@@ -25,7 +25,7 @@ Use a sample application to see Lunch Money OAuth working end to end before you
 > The sample uses a fixed demonstration user and in-memory stores. It does not provide real application authentication, durable multi-user isolation, production credential storage, deployment configuration, or operational controls. Review its [security guidance](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/SECURITY.md) and [production checklist](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/PRODUCTION_CHECKLIST.md) before adapting any part of it.
 
 <!-- BEGIN GENERATED OAUTH SAMPLE WALKTHROUGH -->
-<!-- Source: lunch-money/lm-oauth-confidential-node-example@c8e4d8338d430a3247a48d6e017aaf68d84bd832:docs/WALKTHROUGH.md -->
+<!-- Source: lunch-money/lm-oauth-confidential-node-example@567516d5e32d89576323119bec7f40a7bee007b7:docs/WALKTHROUGH.md -->
 ## Try OAuth with your Lunch Money account
 
 Use this walkthrough to authorize a real Lunch Money OAuth client, call the Lunch Money API, optionally refresh its credentials, revoke access, and repeat the flow. The sample is a confidential, server-side web client built with Node.js and TypeScript.
@@ -100,10 +100,12 @@ export OAUTH_REDIRECT_URI='http://localhost:4002/oauth/callback'
 export LUNCH_MONEY_API_BASE_URL='{{LUNCH_MONEY_API_BASE_URL}}'
 ```
 
-The Developer Portal replaces `{{LUNCH_MONEY_API_BASE_URL}}` with the API base URL for the environment where you registered the client. If you are reading this walkthrough in the sample repository, use the API base URL provided with your Lunch Money OAuth access. The sample uses that one value for OAuth discovery, token operations, and Lunch Money API requests. A real application should also use [OAuth discovery](https://lunchmoney.dev/oauth/authorization-code#configure-lunch-money-with-discovery) instead of hard-coding authorization, token, and revocation endpoint URLs. `PORT` is optional and defaults to `4002`.
+The Developer Portal replaces `{{LUNCH_MONEY_API_BASE_URL}}` with the API base URL for the environment where you registered the client, so the alpha guide configures alpha explicitly. If you are reading this walkthrough in the sample repository with a production client, omit the `LUNCH_MONEY_API_BASE_URL` export; the sample defaults to `https://api.lunchmoney.dev`. For a beta or alpha client, use the exact URL supplied by Lunch Money. The client registration and API base URL must belong to the same environment. The sample uses that value for OAuth discovery, token operations, and Lunch Money API requests. A real application should also use [OAuth discovery](https://lunchmoney.dev/oauth/authorization-code#configure-lunch-money-with-discovery) instead of hard-coding authorization, token, and revocation endpoint URLs. `PORT` is optional and defaults to `4002`.
 
 `SESSION_SECRET` is also optional for this local sample. If it is absent, the process creates a new random cookie-signing secret when it starts. Because all browser sessions, authorization attempts, and credentials are held in memory and cleared on restart, the generated secret can be cleared at the same time. A production application must instead provide a strong `SESSION_SECRET`, keep it stable across restarts, and not rotate it for each OAuth authorization.
 
+Alternatively, copy [`env.example`](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/567516d5e32d89576323119bec7f40a7bee007b7/env.example) to `.env` as described in [Load settings from a `.env` file](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/567516d5e32d89576323119bec7f40a7bee007b7/README.md#load-settings-from-a-env-file).
+
 > [!WARNING]
 > **Keep credentials private**
 > Keep the client secret in a private local environment or secret manager. Never paste it into documentation, AI chats or prompts, committed files, screenshots, browser code, logs, support requests, or commands retained in shared shell history.
@@ -123,10 +125,24 @@ If a form reports **Invalid CSRF token**, reload the page and try again. This co
 1. Choose **Connect Lunch Money**.
 2. Sign into Lunch Money as the user who created the development client.
 3. Select one of that user's budgeting accounts and approve access.
-4. After the browser returns to `http://localhost:4002/oauth/callback`, choose **Call /v2/me**.
+4. After the browser returns to `http://localhost:4002/oauth/callback`, expand **How this authorization was processed** to follow the callback, server-side code exchange, `/v2/me` identity check, and resulting active-user decision. Then choose **Call /v2/me**.
 
 The sample calls `GET /v2/me` from its Node.js server using the server-held access token. It validates the response against the documented `userObject` schema and displays the returned profile fields. The access token is never sent to the browser.
 
+The processing panel links each teaching step to its implementation. It deliberately does not reveal credential values. To see the normalized credential response while developing locally, set a debugger breakpoint immediately after `exchangeCallback()` returns in `completeAuthorization`, then inspect `tokenSet`. Do not print tokens in browser output or logs.
+
+If you want to verify the access token outside the sample, copy it from the local debugger and read it silently into a temporary shell variable. This keeps the credential itself out of shell history:
+
+```sh
+read -s LM_ACCESS_TOKEN
+curl --fail-with-body \
+  --header "Authorization: Bearer ${LM_ACCESS_TOKEN}" \
+  "${LUNCH_MONEY_API_BASE_URL}/v2/me"
+unset LM_ACCESS_TOKEN
+```
+
+Press <kbd>Enter</kbd> after pasting the token at the hidden prompt. Treat it as a live secret: use a private local terminal, do not paste it directly into a command, and clear the variable when finished. This debugger workflow is for understanding and testing the sample. A production application should inspect encrypted credential records only through privileged operational tooling that redacts secret values.
+
 Open Lunch Money's [Connected Apps](https://my.lunchmoney.app/connected-apps) page in another tab, keeping the sample available so you can return to it. The client you just authorized should appear with the details you registered. If you plan to exercise refresh, return to the sample without revoking access yet; revocation ends this authorization's continuing access.
 
 ### 6. Optionally refresh access
@@ -139,9 +155,9 @@ If you registered only `me:read`, Lunch Money does not issue a refresh token and
 
 The sample allows an immediate refresh so you can observe the flow. A production application normally decides when to refresh using expiration information from the token response or after an API authentication failure.
 
-### 7. Revoke and verify access
+### 7. Disconnect the active budget
 
-Choose **Revoke and verify**.
+Choose **Disconnect active budget**.
 
 - If the connection has a refresh token, the sample revokes it to revoke the entire grant.
 - If the connection has only an access token, the sample revokes that access token.
@@ -159,13 +175,13 @@ To see what happens when a Lunch Money user disconnects the client:
 3. Revoke the client's access there.
 4. Return to the sample and choose **Call /v2/me**.
 
-The request should fail because Lunch Money no longer accepts the stored access token. Choose **Local reset only** to remove the now-unusable local credential and browser session before starting again.
+The request should fail because Lunch Money no longer accepts the stored access token. Choose **Forget local credential only** to remove the now-unusable local credential before starting again.
 
 ### Local reset is not revocation
 
-**Local reset only** clears the sample's browser session and locally stored credential. It does not contact Lunch Money and does not revoke active access.
+**Forget local credential only** clears the active budget's locally stored credential after confirmation. It does not contact Lunch Money and does not revoke active access.
 
-When access is still active, revoke it first through **Revoke and verify** or Lunch Money's Connected Apps page. Use local reset by itself only when the remote authorization has already been revoked or you deliberately want to clear this disposable local demonstration.
+When access is still active, revoke it first through **Disconnect active budget** or Lunch Money's Connected Apps page. Forget the local credential by itself only when the remote authorization has already been revoked or you deliberately want to clear this disposable local demonstration.
 
 ### Why `localhost` works
 
@@ -179,7 +195,7 @@ When access is still active, revoke it first through **Revoke and verify** or Lu
 
 After the flow succeeds, connect each action you performed to the code that implemented it, then decide how those responsibilities fit into your own application.
 
-Before adapting the code, read the repository's [OAuth code guide](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/c8e4d8338d430a3247a48d6e017aaf68d84bd832/src/oauth/README.md), [security model](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/c8e4d8338d430a3247a48d6e017aaf68d84bd832/SECURITY.md), [production checklist](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/c8e4d8338d430a3247a48d6e017aaf68d84bd832/PRODUCTION_CHECKLIST.md), and [troubleshooting guide](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/c8e4d8338d430a3247a48d6e017aaf68d84bd832/TROUBLESHOOTING.md).
+Before adapting the code, read the repository's [OAuth code guide](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/567516d5e32d89576323119bec7f40a7bee007b7/src/oauth/README.md), [security model](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/567516d5e32d89576323119bec7f40a7bee007b7/SECURITY.md), [production checklist](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/567516d5e32d89576323119bec7f40a7bee007b7/PRODUCTION_CHECKLIST.md), and [troubleshooting guide](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/567516d5e32d89576323119bec7f40a7bee007b7/TROUBLESHOOTING.md).
 <!-- END GENERATED OAUTH SAMPLE WALKTHROUGH -->
 
 ## Understand the confidential teaching code
@@ -221,6 +237,19 @@ visible or selectable. Applications that add their own sign-in system must put
 that pair inside the authenticated application user's storage and ownership
 boundary.
 
+The native sample defaults to the production API at
+`https://api.lunchmoney.dev`. This Developer Portal is configured for
+`{{LUNCH_MONEY_API_BASE_URL}}`. If this differs from production, set the
+sample's API-base override before starting it:
+
+```sh
+export EXPO_PUBLIC_LUNCH_MONEY_API_BASE_URL='{{LUNCH_MONEY_API_BASE_URL}}'
+```
+
+Register the OAuth client in the same environment as that API base URL. A
+client registration from one environment cannot be used with another
+environment's authorization server and API.
+
 The native repository's [walkthrough](https://github.com/lunch-money/lm-oauth-native-expo-example/blob/main/docs/WALKTHROUGH.md) is the canonical hands-on guide;
 complete the registration, development-build, authorization, `/v2/me`,
 optional refresh, revocation, and local-reset walkthrough there.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunch-money/developer-docs",
-  "version": "2.11.2-preview.6",
+  "version": "2.11.2-preview.8",
   "description": "Developer documentation content for Lunch Money APIs",
   "exports": {
     ".": "./package.json",