@particle-academy/fancy-connector-core 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -6,6 +6,84 @@ All notable changes to `fancy-connector-core` are documented here, in
 **This package is pre-1.0, so breaking changes land in MINOR releases.** The
 version number is not a promise it can keep yet; the entries below are.
 
+## [0.14.0] - 2026-11-07
+
+### Added
+
+- **`readWithCursor` / `CursorRead::read`: a read that resumes from a
+  HOST-HELD cursor, and pages.** It's for Gmail's `history.list` after a push,
+  and Drive's `changes.list` after a channel notification, where the delivery
+  says only that something moved. The package holds no state: the host stores
+  the cursor, passes it in, and persists `cursor.next` when the run succeeds.
+  - `next` is read ONLY from the LAST page: Gmail's `historyId` is the
+    mailbox's current one on every page.
+  - More than `page.maxPages` is refused as `cursor-overflow`, never a partial
+    read.
+  - The provider's `expiredStatus` (Gmail's 404) is refused as
+    `cursor-expired`. Every other failure is rethrown unchanged.
+  - No stored cursor is refused as `cursor-missing`, and the provider is not
+    called.
+  - A collected list that's absent is `[]`; one that isn't a list is
+    `bad-page`.
+  - Cursors are strings.
+  - A refusal carries the caller's `resyncQuery`.
+
+  The reasons ship as data (`CURSOR_READ_REASONS`, `CursorRead::REASONS`).
+  Both runtimes read `fixtures/cursor-read/cases.json`: 14 authored cases
+  against a scripted provider, every call compared.
+
+### Changed
+
+- The README and the npm description now say plainly that PHP apps install
+  the package with Composer.
+- `fixtures/jwt` gains rows 0015 to 0024: signature length, values at and
+  above the modulus, and valid RSA signatures over malformed PKCS#1 v1.5
+  blocks.
+
+`CONNECTOR_API_VERSION` is unchanged: everything here is optional.
+
+## [0.13.0] - 2026-11-01
+
+### Added
+
+- **`verifyJwt` / `Jwt::verify`: RS256 JWT verification against keys the
+  HOST supplies.** The core never fetches a key set. Every rule fails closed:
+  RS256 only, with `none` and `HS256` refused by name; a `kid` must name a
+  supplied key; `exp` is required and `nbf` honoured, both with 60 s of
+  leeway; the audience is REQUIRED unless the caller passes `null` on
+  purpose; the issuer is matched when given. Reasons are fixed strings. Both
+  runtimes read `fixtures/jwt/cases.json`, led by RFC 7515 Appendix A.2,
+  which verifies from the RFC's own inputs.
+- **The `oidc-jwt` verification scheme, for Google Cloud Pub/Sub push**
+  (Gmail's `users.watch` notifications). `verifyOidcDelivery` /
+  `OidcDelivery::verify`, reached through `verifyDelivery`'s new optional
+  fifth argument, an `OidcExpectation` (`keys`, `audience`, `principal`, all
+  the host's). It refuses every push when any of the three is unconfigured,
+  reads `Bearer <token>` case-insensitively, verifies the JWT, then requires
+  the scheme's `principalClaim` (`email`) to EQUAL the configured service
+  account and its `verifiedClaim` (`email_verified`) to be the literal
+  `true`. The principal check is what stops a stranger's push subscription,
+  aimed at your URL with your URL as its audience, whose token Google signs
+  correctly. `fixtures/oidc-delivery/cases.json` has 19 authored rows.
+- **The `pubsub-push` decode kind.** `decodePubSubPush` /
+  `PubSubPush::decode`, also through `decodeDelivery` /
+  `DeliveryDecode::apply`. It unwraps Pub/Sub's push envelope to
+  `{subscription, messageId, publishTime, attributes, deliveryAttempt, data}`.
+  `data` may be in either base64 alphabet, padded or not, and is parsed as
+  JSON. Malformed input is refused BY NAME: `not-json`, `missing-message`,
+  `missing-data`, `bad-encoding` or `data-not-json`. Held to the 13-case
+  corpus under `fixtures/pubsub-push/`.
+
+### Changed
+
+- `DeliveryDecode` (TS) is now a union,
+  `{kind: "form-field-json", field} | {kind: "pubsub-push"}`, and
+  `DELIVERY_DECODE_KINDS` / `DeliveryDecode::KINDS` gain `"pubsub-push"`. A
+  declaration written as a literal is unaffected. Code that reads `.field` off
+  a `DeliveryDecode` it did not construct must narrow on `kind` first.
+
+`CONNECTOR_API_VERSION` is unchanged: everything here is optional.
+
 ## [0.12.0] - 2026-11-01
 
 ### Added

package/README.md

@@ -9,10 +9,15 @@ versioned rendering, chain posting, declared metric shapes, credential-free
 probes, and API-drift reporting.
 
 Matched **TypeScript + PHP**, one repository, **zero runtime dependencies in
-either ecosystem**.
+either ecosystem**. TypeScript and Node apps install it from npm; **PHP apps
+(Laravel included) install it with Composer**. Both packages are released
+together at the same version.
 
 ```bash
+# TypeScript / Node
 npm install @particle-academy/fancy-connector-core
+
+# PHP (Composer)
 composer require particle-academy/fancy-connector-core
 ```