esoul-sdk 0.19.1 → 0.20.0

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# esoul-sdk changelog
+
+Releases before 0.20.0 are recorded in the repository history only.
+
+## 0.20.0
+
+### Added
+
+- **Platform accounts (Google): `credentials` in `plugin.json`.** An app declares one slot,
+  `credentials: { <slot>: { family: "google", scopes, why, label?, background? } }`, with scopes
+  from `gmail.readonly`, `gmail.modify`, `gmail.send`, `gmail.compose`, `gmail.labels`,
+  `calendar.events`, `calendar.readonly`, `contacts`, `contacts.readonly`, `drive.readonly`,
+  `drive.file` (short or full URL). The person assigns a Google account to the app in Account
+  settings → Google. Schema: `PluginCredentialsSchema`, `GOOGLE_CREDENTIAL_SCOPES`,
+  `normaliseCredentialScopes`. See `docs/08-connections.md` → "Platform accounts (Google)".
+- **`credentials(ctx).slot(name)` in `esoul-sdk/server`: a proxy, never a token.** `.fetch(url, init)`
+  is the standard `fetch` with the account's access added by the platform, sent only when the URL
+  is a clean `https://` Google API URL that one of the slot's scopes reaches for that method, and
+  the caller is the account's owner (or the app's own background work when the slot declares
+  `background: true`). `.status()` answers `{ state: "ready" | "not_bound" | "needs_consent" |
+  "reconnect" | "not_allowed", account?, missingScopes?, connectUrl?, reason? }`. A refusal throws
+  `CredentialUnavailable` (`isCredentialUnavailable`) with a `code` a tool can relay.
+- **`useCredential(slot, { nodeId })` and `<ConnectAccount/>` in `esoul-sdk/react`.** The screen
+  asks the same question `status()` answers, for the person looking at it; `connect()` sends the
+  owner to consent, a reconnect, or Account settings → Google.
+- **`simGmail()` in `esoul-sdk/testing`: a fake Gmail at the HTTP level.** The endpoints the
+  platform's mail code calls, with Gmail's wire shapes and error envelopes; mailboxes that deliver
+  to each other and thread like Gmail; history and push; scripted counterparties (`addPersona`,
+  `crowd`) on a virtual clock (`advance`); deterministic faults; a seeded, production-shaped
+  synthetic corpus (300 messages by default); `snapshot()` / `simGmail({ restore })`.
+  Also `DEFAULT_SIM_ACCOUNT`, `DEFAULT_CROWD_MIX`. See `src/testing/sim-gmail/README.md` in the
+  repository. No Node built-ins: it runs in jest, Node, Next.js and the browser.
+- In a Forge box (esoul-app-host 0.3.0), the Google slot is bound to one simulated account and
+  answered by `simGmail`; the installed app uses the person's real account.
+
+### Changed
+
+- **The env-name rule (W-060).** A `connections` entry's `clientIdEnv` / `clientSecretEnv` must
+  name the app's OWN env vars: `PLUGIN_<APP ID upper-cased, - as _>__<NAME>`, e.g.
+  `PLUGIN_MY_APP__CLIENT_ID`. Any other name is refused by the manifest schema; a name ending in
+  `_WEBHOOK_TOKEN` is the platform's and is refused too (`pluginEnvPrefix`,
+  `pluginEnvNameProblem`). An app that named `GOOGLE_CLIENT_ID` or any other platform variable
+  must rename it and have the owner set the new name.
+- `authorizeUrl` / `tokenUrl` must be `https://` (plain `http://` only to the loopback, for a mock
+  provider such as `startMockOAuth`) — `pluginEndpointProblem`.
+- The package no longer ships compiled test files (`src/**/*.test.ts` are excluded from `dist/`).