@ophelio/sdk 0.5.0 → 0.5.1

package/README.md

@@ -30,9 +30,11 @@ if (result.admitted) {
 }
 
 // Offline gate cache
-const { members, generated_at } = await ophelio.members.sync()
+const { members, generated_at } = await ophelio.members.sync({
+  targets: ['venue_a'], // roster for this gate; optional
+})
 // later, incremental:
-await ophelio.members.sync({ since: generated_at })
+await ophelio.members.sync({ since: generated_at, targets: ['venue_a'] })
 ```
 
 ## Authentication
@@ -160,7 +162,7 @@ Everything reachable with an API key is covered:
 | Namespace                       | Methods                                                                                                                                                                                                                                                                                                                                                                                      |
 | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `admit`                         | `check({ card, targets? })`                                                                                                                                                                                                                                                                                                                                                                  |
-| `members`                       | `sync({ since? })`, `get(id)`, `listEntitlements(id, { type?, targets? })`, `update(id, ...)`, `remove(id)`, `setPrimary(id)`, `reissueCard(id, { note? })`                                                                                                                                                                                                                                  |
+| `members`                       | `sync({ since?, targets? })`, `get(id)`, `listEntitlements(id, { type?, targets? })`, `update(id, ...)`, `remove(id)`, `setPrimary(id)`, `reissueCard(id, { note? })`                                                                                                                                                                                                                        |
 | `memberships`                   | `list(params?)`, `get(id)`, `create(...)`, `update(id, ...)`, `cancel(id, ...)`, `uncancel(id)`, `renew(id, ...)`, `upgrade(id, ...)`, `downgrade(id, ...)`, `listMembers(id)`, `addMember(id, ...)`, `listScheduledChanges(id, params?)`, `cancelScheduledChange(id, changeId)`, `listTransactions(id, params?)`, `listTermTransactions(id, termId, params?)`, `createTransaction(id, ...)` |
 | `customers`                     | `list(params?)`, `get(id, params?)`, `create(...)`, `update(id, ...)`, `delete(id)`, `listMemberships(id, params?)` — `list`/`get` accept `view: 'full'` to include `membership_summary`                                                                                                                                                                                                     |
 | `entitlements`                  | `redeem(...)`, `recordUsage(...)`, `list()`, `get(id)`, `create(...)`, `update(id, ...)`, `delete(id)`                                                                                                                                                                                                                                                                                       |
@@ -338,10 +340,11 @@ rejected, not registered for you.
 ### Target context
 
 A read can say where it is being made, and the entitlements it gets back are
-checked against the availability rows for that place. `admit.check` and
-`members.listEntitlements` take `targets` — a set of registered target codes,
-sent comma-separated on the wire — and `entitlements.recordUsage` takes a
-singular `target`, because one usage event happens at one place.
+checked against the availability rows for that place. `admit.check`,
+`members.listEntitlements` and `members.sync` take `targets` — a set of
+registered target codes, sent comma-separated on the wire — and
+`entitlements.recordUsage` takes a singular `target`, because one usage event
+happens at one place.
 
 ```ts
 const result = await ophelio.admit.check({
@@ -357,8 +360,9 @@ for (const entitlement of result.entitlements) {
 }
 ```
 
-**Three cases, answered differently.** Omitting `targets` says nothing about
-where the request is: every target restriction is then treated as met, and
+**Three cases, answered differently on `admit.check` and
+`members.listEntitlements`.** Omitting `targets` says nothing about where the
+request is: every target restriction is then treated as met, and
 `target_context_applied` comes back `false`. Passing `[]` says the caller names
 no targets, so only benefits valid everywhere come back. Passing codes means a
 benefit has to name one of them. Dates are checked in all three cases.
@@ -369,9 +373,20 @@ rather than dropped, so a typo cannot pass for a benefit that does not apply.
 
 **The parameter does a different job on each endpoint.** At the gate it is part
 of the admission decision; on `members.listEntitlements` it filters the list you
-get back. `members.sync` takes no targets at all — each member's entitlements
-are a snapshot taken at the moment of the sync, and the gate that caches them
-applies no rules of its own.
+get back. On `members.sync` it is the scope of what one gate stores for later:
+each member's entitlements are a snapshot taken at the moment of the sync, read
+back during an outage without being checked again, so the targets you sync with
+settle what that gate can grant while it is offline. The gate applies no rules
+of its own.
+
+**`members.sync` differs from the other two in two ways, both deliberate.** An
+empty `targets` is refused with a 400 there. It is not read as naming no
+targets, so it never returns only the benefits valid everywhere. And the
+per-project setting below does not apply to it — a sync that omits `targets`
+is always answered and returns the whole roster. The roster is the copy a gate
+falls back on when it cannot reach us, so a quietly shortened or unfetchable
+one would go unnoticed until the outage it exists for. Neither is an oversight
+to be tidied up into consistency.
 
 `valid_on` and `valid_at` list only what an entitlement **matched**. `valid_on`
 is omitted when no date restricts it, and `valid_at` when no place does. What
@@ -380,10 +395,11 @@ benefit is valid, never which restrictions the member missed. Read the two
 lists separately — because an entitlement applies if any one row matches, a
 date in `valid_on` and a place in `valid_at` need not come from the same row.
 
-A project can require every read to say where it is. Once all of its gates send
-their own `targets`, an operator turns the setting on, and from then on a read
-that omits `targets` altogether is refused with a 400. Passing `[]` is not the
-same as omitting it: that read has said where it is and named no targets, so it
-is still answered, exactly as the three cases above describe. It is a
+A project can require `admit.check` and `members.listEntitlements` to say where
+they are. Once all of its gates send their own `targets`, an operator turns the
+setting on, and from then on one of those reads that omits `targets` altogether
+is refused with a 400. `members.sync` is exempt, as above. Passing `[]` is not
+the same as omitting it: that read has said where it is and named no targets,
+so it is still answered, exactly as the three cases above describe. It is a
 per-project setting rather than anything the client sends, so start sending
 `targets` before expecting it to be required.

package/dist/index.cjs

@@ -687,12 +687,31 @@ var MembersResource = class extends APIResource {
 	/**
 	* Active-member list for offline gate caching. Pass the previous
 	* response's `generated_at` as `since` to fetch incrementally.
+	*
+	* `targets` names the venue, zone, shop or gate this roster is for, and
+	* settles what the gate can grant while it is offline: each member's
+	* entitlements are stored as they stand at the moment of the sync and are
+	* read back during an outage without being checked again. Omit it for the
+	* whole roster. Codes are matched exactly, so send them back verbatim from
+	* `targetCodes.list()` — an unregistered one is refused with a 400.
+	*
+	* Two things work differently here than on `admit.check` and
+	* `members.listEntitlements`, both on purpose. An empty `targets` is
+	* refused with a 400. It is not read as naming no targets, so it never
+	* returns only the benefits valid everywhere. And a project that requires
+	* every read to say where it is still answers a sync that omits `targets`.
+	* The roster is what a gate falls back on when it cannot reach us, so a
+	* quietly shortened or unfetchable copy would only show up during the
+	* outage it was kept for.
 	*/
 	sync(params = {}, options) {
 		return this.transport.request({
 			method: "GET",
 			path: "/api/v1/members/sync",
-			query: { since: params.since },
+			query: {
+				since: params.since,
+				targets: params.targets
+			},
 			retryable: true,
 			options
 		});

package/dist/index.d.cts

@@ -5888,9 +5888,26 @@ declare class MembersResource extends APIResource {
   /**
    * Active-member list for offline gate caching. Pass the previous
    * response's `generated_at` as `since` to fetch incrementally.
+   *
+   * `targets` names the venue, zone, shop or gate this roster is for, and
+   * settles what the gate can grant while it is offline: each member's
+   * entitlements are stored as they stand at the moment of the sync and are
+   * read back during an outage without being checked again. Omit it for the
+   * whole roster. Codes are matched exactly, so send them back verbatim from
+   * `targetCodes.list()` — an unregistered one is refused with a 400.
+   *
+   * Two things work differently here than on `admit.check` and
+   * `members.listEntitlements`, both on purpose. An empty `targets` is
+   * refused with a 400. It is not read as naming no targets, so it never
+   * returns only the benefits valid everywhere. And a project that requires
+   * every read to say where it is still answers a sync that omits `targets`.
+   * The roster is what a gate falls back on when it cannot reach us, so a
+   * quietly shortened or unfetchable copy would only show up during the
+   * outage it was kept for.
    */
   sync(params?: {
     since?: string;
+    targets?: string[];
   }, options?: RequestOptions): Promise<MemberSyncResponse>;
   get(id: string, options?: RequestOptions): Promise<Member>;
   /**

package/dist/index.d.mts

@@ -5888,9 +5888,26 @@ declare class MembersResource extends APIResource {
   /**
    * Active-member list for offline gate caching. Pass the previous
    * response's `generated_at` as `since` to fetch incrementally.
+   *
+   * `targets` names the venue, zone, shop or gate this roster is for, and
+   * settles what the gate can grant while it is offline: each member's
+   * entitlements are stored as they stand at the moment of the sync and are
+   * read back during an outage without being checked again. Omit it for the
+   * whole roster. Codes are matched exactly, so send them back verbatim from
+   * `targetCodes.list()` — an unregistered one is refused with a 400.
+   *
+   * Two things work differently here than on `admit.check` and
+   * `members.listEntitlements`, both on purpose. An empty `targets` is
+   * refused with a 400. It is not read as naming no targets, so it never
+   * returns only the benefits valid everywhere. And a project that requires
+   * every read to say where it is still answers a sync that omits `targets`.
+   * The roster is what a gate falls back on when it cannot reach us, so a
+   * quietly shortened or unfetchable copy would only show up during the
+   * outage it was kept for.
    */
   sync(params?: {
     since?: string;
+    targets?: string[];
   }, options?: RequestOptions): Promise<MemberSyncResponse>;
   get(id: string, options?: RequestOptions): Promise<Member>;
   /**

package/dist/index.mjs

@@ -686,12 +686,31 @@ var MembersResource = class extends APIResource {
 	/**
 	* Active-member list for offline gate caching. Pass the previous
 	* response's `generated_at` as `since` to fetch incrementally.
+	*
+	* `targets` names the venue, zone, shop or gate this roster is for, and
+	* settles what the gate can grant while it is offline: each member's
+	* entitlements are stored as they stand at the moment of the sync and are
+	* read back during an outage without being checked again. Omit it for the
+	* whole roster. Codes are matched exactly, so send them back verbatim from
+	* `targetCodes.list()` — an unregistered one is refused with a 400.
+	*
+	* Two things work differently here than on `admit.check` and
+	* `members.listEntitlements`, both on purpose. An empty `targets` is
+	* refused with a 400. It is not read as naming no targets, so it never
+	* returns only the benefits valid everywhere. And a project that requires
+	* every read to say where it is still answers a sync that omits `targets`.
+	* The roster is what a gate falls back on when it cannot reach us, so a
+	* quietly shortened or unfetchable copy would only show up during the
+	* outage it was kept for.
 	*/
 	sync(params = {}, options) {
 		return this.transport.request({
 			method: "GET",
 			path: "/api/v1/members/sync",
-			query: { since: params.since },
+			query: {
+				since: params.since,
+				targets: params.targets
+			},
 			retryable: true,
 			options
 		});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ophelio/sdk",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Official JavaScript / TypeScript SDK for the Ophel.io membership & entitlement API.",
   "license": "MIT",
   "author": "Ophel.io",