@01.software/sdk 0.74.0 → 0.75.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @01.software/sdk
 
+## 0.75.0
+
+### Minor Changes
+
+- 3ab46a5: Allow `returnWithRefund` to complete an existing approved Return with `existingReturnId`, preserving the server-owned approval and idempotent replay. Clarify that the initial shipping refund is added separately to the line refund amount.
+
+  BREAKING (0.x minor): `returnWithRefund` now returns `ReturnWithRefundResponse`, matching the actual bounded completion receipt instead of full Return/Transaction documents. Use `refundSeq` and optional `notificationWarning`; read full documents separately when additional fields are needed. Completions without a provider transaction have both `transaction` and `refundSeq` set to null.
+
+- 2a3cdbe: BREAKING (0.x minor): isolate SDK collection declarations from Console Config and Payload global type augmentation. Internal collection slugs no longer resolve to generated documents through `CollectionType`; existing browser/server buckets and runtime access checks are unchanged. Use documented operation DTOs where provided; code managing internal collections must use its application-owned Payload types.
+
+  Remove two unavailable internal relations from populated admission-hold types, including nested order/refund graphs. Preserve the other raw document fields and existing named compatibility types, including `WebhookWithoutSecret`. Consumer Payload applications retain ownership of their own `GeneratedTypes` augmentation. Compatibility disposition follows ADR 0138 and #8960.
+
+- 78bd724: Add opt-in event registration email verification and its typed SDK helper on
+  `client.events` and `server.events`. The Events starter guides new deployments to
+  enable the event email-verification setting and shows an email code step for those
+  events; opt-out events keep immediate registration. Sandbox does not deliver
+  verification codes yet, so test registration there with an opt-out event.
+  Confirmation emails now have a tenant/recipient rolling-hour cap without changing
+  successful registration.
+- 7aa55a1: BREAKING (0.x minor): createFulfillment and updateFulfillment now return FulfillmentMutationResponse instead of the raw Fulfillment document. Shipment mutation receipts retain shipment state, tracking and timestamps while excluding expanded relations and document extensions.
+
+  Migration: tenant, order and fulfillmentOrder are IDs rather than populated documents; fulfillmentOrder is null for legacy unlinked shipments. Branch on null before using that relationship. The receipt no longer includes items, adminNotes, metadata, method or deletedAt. Replace shipment.items?.docs and other document-only reads with an authorized server.collections.from('fulfillments').findById(receipt.id, { joins: { items: { limit: 100 } } }) read. Use the returned order or fulfillmentOrder ID with an authorized read of its owning collection when related details are needed. Remove dependencies on internal method values and populated tenant internals. Authorized collection reads retain their normal field access rules.
+
+- 65f2725: Add `customer.auth.requestWithdrawalCode()` and `withdraw({ emailCode })` for purpose-limited withdrawal reauthentication on accounts without a local password. Existing `withdraw(password)` calls remain supported. Submit the code using the same refresh-family session (preserved across access-token refresh); successful withdrawal clears local credentials. Code-specific reauthentication reasons have a public type.
+
+### Patch Changes
+
+- ed5deda: Classify workspace social provider configuration as internal and synchronize the generated document types without exposing a public collection API.
+- 86ba927: Clarify that prepareFulfillmentOrder must precede createFulfillment because shipment creation requires an in-progress fulfillment order.
+- f8ec410: Update the generated EventOccurrence field documentation to match the Console copy: describe parentPublic as the parent event's public status, separate from sales conditions, and drop the capacity and registrations editing hints. The type structure is unchanged.
+- 79a9e72: Regenerate the `Tenant.tenantPurpose` field documentation in the raw collection document types to match the Console copy: TEST creation has ended and the purpose of retained records is immutable. The type structure is unchanged.
+- c5470fd: Expose the server-only Membership billing anchor day and its source in generated collection types.
+- e0c7231: Refresh the generated Tenant purpose documentation after TEST creation retirement.
+  The SDK type structure and wire format remain unchanged.
+- 287a638: Synchronize generated tenant notification settings and notification event types for occurrence time and venue change notices.
+
 ## 0.74.0
 
 ### Minor Changes

package/README.md

@@ -979,6 +979,12 @@ const client = createClient({ publishableKey: '...' })
 const query = createQueryHooks(client, getStorefrontQueryClient())
 ```
 
+SDK document declarations are independent of your application's Payload
+`GeneratedTypes`: importing the SDK does not register the Console schema in
+Payload. `CollectionType<T>` resolves browser-public and server-only raw
+collection documents; internal slugs remain classification vocabulary only.
+Existing named raw exports, including `Tenant`, keep their compatibility shapes.
+
 ## Advanced: direct Payload queries (escape hatch)
 
 Most consumers should use the helper APIs above (`commerce.product.detail`, etc.). The query builder below is the escape hatch for advanced cases the helpers do not cover: bulk operations, custom filter combinations, or fields the helper response does not expose.
@@ -1569,12 +1575,36 @@ erase personal data or free the email for a new registration.
 Branch on `SDKError.apiReason`: `active_membership_exists` (409) requires the
 membership to end first, including scheduled cancellations still in an active
 status; `reauthentication_unavailable` (409) means no local password is set and
-the customer should contact the tenant administrator. Incorrect passwords use
+the customer must request a withdrawal-only email code. Incorrect passwords use
 the shared login attempt counter and temporary lock (`account_locked`, 423).
 Refusal leaves the SDK credentials intact. Server keys cannot withdraw on a
 customer's behalf. Operator restore continues to follow the existing archive
 rules; the withdrawal timestamp is retained.
 
+Customers without local password material, including social-only accounts, use
+withdrawal-only email reauthentication:
+
+```ts
+await client.customer.auth.requestWithdrawalCode()
+// Collect the code sent to the stored email, keeping the same refresh-family session.
+const { withdrawnAt } = await client.customer.auth.withdraw({ emailCode })
+```
+
+The six-digit code expires after 10 minutes, is single-use and cannot sign in.
+Ten invalid proofs block code verification for 15 minutes. Reissuing does not
+reset that budget. Refresh within the same family preserves the proof; a new
+login/family needs a new code. Issuance accepts JSON `{}` and is limited to
+5 requests per minute and 10 per hour per tenant/customer.
+`password_reauthentication_required` (409) means this account must use its local
+password. `withdrawal_session_refresh_required` (409) means its access token
+predates the stable session claim: refresh the existing direct session with
+`customer.auth.refreshToken()`, or the hosted session with `customer.oauth.refresh()`,
+store the returned pair, and retry code issuance. These code-specific 409 values
+are typed by `CustomerWithdrawalCodeReauthenticationReason`; common HTTP/auth
+reasons still apply. No code is issued before this refresh.
+No terms acknowledgement or new login session is required. `invalid_code` (401)
+requires a valid new proof; `service_unavailable` (503) keeps withdrawal denied.
+
 ### Market discovery
 
 Discover a tenant's active buyer markets and resolve the default market. These
@@ -2049,6 +2079,7 @@ await server.commerce.orders.createReturn({
 await server.commerce.orders.updateReturn({ returnId, status })
 await server.commerce.orders.returnWithRefund({
   orderNumber,
+  existingReturnId?,
   returnItems: [{ orderItem, quantity, restockingFee? }],
   refundAmount,
   returnShippingFee?,
@@ -2058,6 +2089,26 @@ await server.commerce.orders.returnWithRefund({
 })
 ```
 
+**BREAKING (0.x minor):** `createFulfillment` and `updateFulfillment` return `FulfillmentMutationResponse` instead of a raw `Fulfillment` document. Shipment state, tracking and timestamps remain in the receipt.
+
+- `tenant`, `order` and `fulfillmentOrder` contain IDs instead of populated documents. Legacy unlinked shipments return `fulfillmentOrder: null`; check for null before reading the related work order.
+- `items`, `adminNotes`, `metadata`, `method` and `deletedAt` are absent from the receipt. Replace `shipment.items?.docs` and other document-only reads with `server.collections.from('fulfillments').findById(receipt.id, { joins: { items: { limit: 100 } } })` under authorized server credentials. Read related details from their owning collection using the returned ID. Remove dependencies on internal `method` values and populated tenant internals; collection reads retain their normal field access rules.
+
+`returnWithRefund` can complete an existing approved Return by passing
+`existingReturnId` with its `orderNumber`. The server uses the persisted approval's
+items, amounts, fees and reason; caller values cannot widen it. Keep the required
+`returnItems` and positive `refundAmount` in the request. The line refund is after
+return shipping/restocking fees; the initial shipping refund is added separately.
+Repeat the same request and `idempotencyKey` after response loss.
+
+The result is a bounded completion receipt: `return` includes only `id`,
+`status`, `refundAmount`, `returnShippingFee`, `initialShippingRefundAmount` and
+`completedAt`. A provider refund includes `transaction` (`id`, `type`, `kind`,
+`status`, `amount`, `providerEventId`) and numeric `refundSeq`; a completion
+without a provider transaction has `transaction: null` and `refundSeq: null`.
+`notificationWarning` may report a post-commit display/notification problem;
+the refund has completed. Read full documents separately if needed.
+
 ### Commerce Discounts / Shipping
 
 Available on both Client (customer JWT) and ServerClient (secretKey).
@@ -2381,6 +2432,12 @@ replacement API. Pass an empty list to clear codes. Singular `admission`,
 Browser `mine()`/`merge({ guestCartToken })` derive customer identity from the
 JWT; server calls require an explicit `customerToken`.
 
+### Event discovery and unlisted links
+
+`client.events.getRange()` lists published events with `visibility=public`. Its pages and totals exclude `unlisted` events, as do Publishable Key raw event and occurrence lists and counts. For an unlisted link, retain the event and occurrence IDs and read each with `client.collections.from('events').findById(eventId)` and `client.collections.from('event-occurrences').findById(occurrenceId)`. Registration remains available when the event and occurrence meet the registration rules.
+
+An id or slug filter on a raw list still follows listing visibility. To make an event discoverable, select `visibility=public`. Refresh cached lists and totals when the server's listing behavior changes.
+
 ### Event admission availability
 
 For paid admission choices, call
@@ -2989,3 +3046,24 @@ zero provider amount and restores credit only. A full-credit Order rejects any
 `pgPaymentId` or `paymentKey`; never invent an identifier. Explicit blank values
 remain invalid. Orders without credit funding retain `400/validation_failed`
 when `pgPaymentId` is omitted. Refund amount, credential, tenant and ecommerce authority remain unchanged.
+
+### Event registration email verification
+
+For an event with **Verify registration email** enabled, call
+`client.events.requestRegistrationEmailVerification(input)` before registering.
+When `verificationRequired` is true, collect the emailed eight-digit code, then
+pass the same input plus `emailVerification: { requestId, code }` to
+`client.events.register`. The code expires after 15 minutes and five attempts.
+No registration or seats exist until successful verification and a fresh capacity
+check. Opt-out events retain the existing register result and immediate behavior.
+Confirmation mail has a ten-per-hour tenant/recipient cap; suppression does not
+cancel registration. Event-cancellation notices are exempt. Verification mail has
+its own three-per-hour cap and a 60-second resend interval, plus ordinary email quota.
+
+The request returns a processing receipt before delivery in Live and Sandbox.
+Recipient limits suppress background delivery behind that same receipt; the
+recipient-independent tenant admission limit still returns synchronous 429.
+Only an active member of the exact Sandbox with a verified current email receives
+the code, using platform From, a `[Sandbox]` subject and no Reply-To. Other
+recipients and ordinary event mail are captured. Sandbox keeps its shared
+100/month non-billable email ceiling. A receipt confirms neither delivery nor seats.

package/dist/client.cjs

@@ -1379,7 +1379,8 @@ var CUSTOMER_AUTH_ENDPOINT_OPERATIONS = {
   resetPassword: operation("customers", "post", "/reset-password"),
   changePassword: operation("customers", "post", "/change-password"),
   revokeRefresh: operation("customers", "post", "/revoke-refresh"),
-  withdraw: operation("customers", "post", "/withdraw")
+  withdraw: operation("customers", "post", "/withdraw"),
+  requestWithdrawalCode: operation("customers", "post", "/withdraw/email-code")
 };
 var EMBEDDED_ADMIN_ENDPOINT_OPERATIONS = {
   show: operation("tenants", "get", "/embedded-admin-app"),
@@ -1393,6 +1394,13 @@ var FIELD_CONFIG_ENDPOINT_OPERATIONS = {
 var EVENTS_ENDPOINT_OPERATIONS = {
   registrations: {
     register: operation("event-registrations", "post", "/register"),
+    requestEmailVerification: operation(
+      "event-registrations",
+      "post",
+      "/request-email-verification"
+    ),
+    emailCancelPage: operation("event-registrations", "get", "/email-cancel"),
+    emailCancel: operation("event-registrations", "post", "/email-cancel"),
     guestLookup: operation("event-registrations", "post", "/guest/lookup"),
     guestLookupByUrl: operation("event-registrations", "get", "/guest/:token"),
     guestCancel: operation("event-registrations", "post", "/guest/cancel"),
@@ -1431,6 +1439,9 @@ var VIDEO_ENDPOINT_OPERATIONS = {
 function resolveOperationTemplate(descriptor) {
   return descriptor.collection ? `/api/${descriptor.collection}${descriptor.path}` : `/api${descriptor.path}`;
 }
+var PAYMENT_DIAGNOSTIC_ENDPOINT_OPERATIONS = {
+  diagnose: operation("tenants", "get", "/payment-diagnostics")
+};
 function resolveOperationPath(descriptor, options) {
   const path = resolveOperationTemplate(descriptor).replace(
     /:([A-Za-z][A-Za-z0-9_]*)/g,
@@ -4805,8 +4816,25 @@ var CustomerAuth = class {
       body: JSON.stringify({ refreshToken })
     });
   }
-  /** Archive the current password account and clear this client's credentials on success. */
-  async withdraw(currentPassword) {
+  /** Send a withdrawal-only code to the current passwordless customer's stored email. */
+  async requestWithdrawalCode() {
+    const token = this.getToken();
+    if (!token) throw new ApiError("Not authenticated", 401);
+    const operation2 = CUSTOMER_AUTH_ENDPOINT_OPERATIONS.requestWithdrawalCode;
+    const result = await this.requestJson(
+      resolveOperationPath(operation2),
+      {
+        method: resolveOperationMethod(operation2),
+        headers: { Authorization: `Bearer ${token}` },
+        body: JSON.stringify({})
+      }
+    );
+    if (!result || typeof result.message !== "string")
+      throw new ApiError("Invalid withdrawal code response", 502);
+    return result;
+  }
+  /** Archive the current account and clear this client's credentials on success. */
+  async withdraw(proof) {
     const token = this.getToken();
     if (!token) throw new ApiError("Not authenticated", 401);
     const operation2 = CUSTOMER_AUTH_ENDPOINT_OPERATIONS.withdraw;
@@ -4815,7 +4843,9 @@ var CustomerAuth = class {
       {
         method: resolveOperationMethod(operation2),
         headers: { Authorization: `Bearer ${token}` },
-        body: JSON.stringify({ currentPassword })
+        body: JSON.stringify(
+          typeof proof === "string" ? { currentPassword: proof } : proof
+        )
       }
     );
     if (!result || typeof result.withdrawnAt !== "string" || !Number.isFinite(Date.parse(result.withdrawnAt)))
@@ -6754,6 +6784,15 @@ var EventsClient = class {
       { useCustomerAuth: true }
     );
   }
+  requestRegistrationEmailVerification(params) {
+    const operation2 = EVENTS_ENDPOINT_OPERATIONS.registrations.requestEmailVerification;
+    return this.execute(
+      resolveOperationPath(operation2),
+      resolveOperationMethod(operation2),
+      buildRegistrationRequestBody(params),
+      { useCustomerAuth: true, noStore: true }
+    );
+  }
   getGuestRegistration(token) {
     return this.execute(
       resolveOperationPath(
@@ -6806,7 +6845,10 @@ function buildRegistrationRequestBody(params) {
     occurrence: params.occurrence,
     ...params.quantity !== void 0 && { quantity: params.quantity },
     ...params.attendee !== void 0 && { attendee: params.attendee },
-    ...params.answers !== void 0 && { answers: params.answers }
+    ...params.answers !== void 0 && { answers: params.answers },
+    ...params.emailVerification !== void 0 && {
+      emailVerification: params.emailVerification
+    }
   };
 }
 function buildGuestCancelRequestBody(token, params) {