@spoketech/hub-client 0.1.0

package/README.md

@@ -0,0 +1,252 @@
+# `@spoketech/hub-client`
+
+Async-first npm client for the Spoke Hub API, with optional Effect-native APIs underneath.
+
+## Install
+
+```bash
+npm install @spoketech/hub-client
+```
+
+## Client Shapes
+
+The package exposes a friendly SDK surface plus the generated API client:
+
+- `makePromiseSpokeClient`: Recommended object-style SDK for normal app and integration code.
+- `makePromiseHubApiClient` / `makePromiseServiceHubApiClient`: Generated Promise client that mirrors HTTP routes.
+- `makeHubApiClient` / `makeServiceHubApiClient`: Raw Effect clients when your app already uses Effect.
+
+The generated client takes a single request object. Depending on the endpoint, that object can contain:
+
+- `path`: Route parameters like `organizationId`, `memberId`, `guestId`, `runId`, or `serviceClientId`.
+- `payload`: JSON request body.
+- `urlParams`: Query-string parameters.
+- `headers`: Per-call headers. Most callers should set auth at client creation time instead.
+
+## Recommended Usage
+
+```ts
+import { makePromiseSpokeClient } from "@spoketech/hub-client";
+
+const { client } = await makePromiseSpokeClient({
+  baseUrl: "https://hub.example.com",
+  clientId: process.env.SPOKE_CLIENT_ID!,
+  privateKey: process.env.SPOKE_PRIVATE_KEY!,
+});
+
+const members = await client.members.list({
+  organizationId: "org_123",
+  responseMode: "med",
+  page: 1,
+  pageSize: 25,
+});
+
+const member = await client.members.get({
+  organizationId: "org_123",
+  memberId: "mem_123",
+  responseMode: "full",
+});
+
+const guests = await client.guests.list({
+  organizationId: "org_123",
+  name: "Jane",
+});
+```
+
+## Live Onsite Resource Calls
+
+For member-source and voucher operations that must run from the venue network, use the onsite resource wrapper. It dispatches the command and waits briefly for the onsite client to complete it. If the onsite client takes longer than `waitMs`, the response includes the accepted command so callers can continue polling or observe webhooks.
+
+```ts
+import { makePromiseOnsiteResourceClient } from "@spoketech/hub-client";
+
+const { client } = await makePromiseOnsiteResourceClient({
+  baseUrl: "https://hub.example.com",
+  clientId: process.env.SPOKE_CLIENT_ID!,
+  privateKey: process.env.SPOKE_PRIVATE_KEY!,
+});
+
+const lookup = await client.members.lookup({
+  organizationId: "org_123",
+  lookupBy: "member_id",
+  lookupValue: "12345",
+  waitMs: 10_000,
+});
+
+if (lookup.settled && lookup.command.status === "completed") {
+  console.log(lookup.command.result);
+}
+
+const voucher = await client.vouchers.issue({
+  organizationId: "org_123",
+  waitMs: 10_000,
+  payload: {
+    memberId: "mem_123",
+    rewardId: "reward_456",
+    quantity: 1,
+  },
+});
+```
+
+The full Spoke client exposes the same live onsite wrapper under `client.onsite`:
+
+```ts
+const { client } = await makePromiseSpokeClient(options);
+
+const lookup = await client.onsite.members.lookup({
+  organizationId: "org_123",
+  lookupBy: "member_id",
+  lookupValue: "12345",
+  waitMs: 10_000,
+});
+```
+
+## Service Client Authentication
+
+```ts
+import { makePromiseServiceHubApiClient } from "@spoketech/hub-client";
+
+const { client } = await makePromiseServiceHubApiClient({
+  baseUrl: "https://hub.example.com",
+  clientId: process.env.SPOKE_CLIENT_ID!,
+  privateKey: process.env.SPOKE_PRIVATE_KEY!,
+});
+
+const organizations = await client.organizations.listOrganizations({
+  urlParams: { page: "1", pageSize: "25", name: "Spoke" },
+});
+```
+
+`baseUrl` should usually be the site origin. The client appends `/api` by default, so requests target `/api/v1/...`. Override `apiBasePath` if your deployment exposes the API somewhere else.
+
+`makePromiseServiceHubApiClient` returns the generated low-level client. It mirrors HTTP routes with `path`, `payload`, and `urlParams`. Prefer `makePromiseSpokeClient` for app and integration code; it keeps object-style inputs while still returning `hubClient` as a raw escape hatch.
+
+## Included Skill
+
+The npm package also ships a Codex skill at `skills/spoke-hub-client/`. If the package is installed in `node_modules`, the skill lives at:
+
+```text
+node_modules/@spoketech/hub-client/skills/spoke-hub-client
+```
+
+## Effect Usage
+
+If you do want the raw Effect client, `makeHubApiClient` and `makeServiceHubApiClient` are still exported.
+
+## Onsite Source Writes
+
+For Odyssey Gaming sources, member creation, update, renewal, lookup, and onsite voucher issuing are command requests, not direct Hub-to-Nexus/SENPOS API calls.
+
+- The Hub publishes a command to the configured onsite agent through AWS IoT Core.
+- The onsite agent runs on the venue network, calls Nexus from the onsite IP, and then posts the result back to Hub through the completion endpoints.
+- The `onsiteCalls.callOnsiteResource` endpoint and onsite resource wrapper wait briefly for completion, then return the accepted command if the onsite client is still working.
+
+Relevant configuration:
+
+- Hub: `AWS_IOT_DATA_ENDPOINT`, `AWS_REGION`, `ONSITE_AGENT_IOT_TOPIC_PREFIX`
+- Onsite agent: `ONSITE_AGENT_TRANSPORT=iot`, `ONSITE_AGENT_IOT_TOPIC_PREFIX`
+
+## Endpoint Reference
+
+All routes below are relative to `/api/v1`. The promise client and the Effect client use the same method names.
+
+### Auth
+
+| Client method | Route | Request | Returns |
+| --- | --- | --- | --- |
+| `client.auth.getAdminSession({})` | `GET /admin/session` | none | `AdminSession` |
+
+### Organizations
+
+| Client method | Route | Request | Returns |
+| --- | --- | --- | --- |
+| `client.organizations.listOrganizations({ urlParams })` | `GET /organizations` | optional `page`, `pageSize`, `name` | `PaginatedOrganizations` |
+| `client.organizations.createOrganization({ payload })` | `POST /organizations` | `CreateOrganizationInput` | `Organization` |
+| `client.organizations.updateOrganization({ path, payload })` | `PATCH /organizations/:organizationId` | `path.organizationId`, `UpdateOrganizationInput` | `Organization` |
+| `client.organizations.deleteOrganization({ path, payload })` | `DELETE /organizations/:organizationId` | `path.organizationId`, `DeletePayload` | `void` |
+
+### Members
+
+| Client method | Route | Request | Returns |
+| --- | --- | --- | --- |
+| `client.members.listOrganizationMembers({ path, urlParams })` | `GET /organizations/:organizationId/members` | `path.organizationId`, optional paging and search `urlParams` | `OrganizationMembersListResponse` |
+| `client.members.getOrganizationMember({ path, urlParams })` | `GET /organizations/:organizationId/members/:memberId` | `path.organizationId`, `path.memberId`, optional `responseMode` | `MemberResponse` |
+| `client.members.listOrganizationMemberMembershipTypes({ path, urlParams })` | `GET /organizations/:organizationId/members/membership-types` | `path.organizationId`, optional `page`, `pageSize` | `PaginatedOrganizationMemberMembershipTypes` |
+| `client.members.listOrganizationMemberRatingGrades({ path, urlParams })` | `GET /organizations/:organizationId/members/rating-grades` | `path.organizationId`, optional `page`, `pageSize` | `PaginatedOrganizationMemberRatingGrades` |
+| `client.members.createOrganizationMember({ path, payload })` | `POST /organizations/:organizationId/members` | `path.organizationId`, `CreateMemberInput` for local-member creation | `Member` |
+| `client.members.requestSourceManagedMemberCreate({ path, payload })` | `POST /organizations/:organizationId/members/source-create` | `path.organizationId`, `RequestSourceManagedMemberCreateInput` for Odyssey/onsite source creation | `OrganizationMemberSourceCommand` |
+| `client.members.requestSourceManagedMemberRenewal({ path, payload })` | `POST /organizations/:organizationId/members/:memberId/source-renewal` | `path.organizationId`, `path.memberId`, `RequestSourceManagedMemberRenewalInput` for Odyssey/onsite source renewal | `OrganizationMemberSourceCommand` |
+| `client.members.updateOrganizationMember({ path, payload })` | `PATCH /organizations/:organizationId/members/:memberId` | `path.organizationId`, `path.memberId`, `UpdateMemberInput` | `Member` |
+| `client.members.deleteOrganizationMember({ path, payload })` | `DELETE /organizations/:organizationId/members/:memberId` | `path.organizationId`, `path.memberId`, `DeletePayload` | `void` |
+
+### Member Sources
+
+| Client method | Route | Request | Returns |
+| --- | --- | --- | --- |
+| `client.memberSources.getOrganizationMemberSource({ path })` | `GET /organizations/:organizationId/member-source` | `path.organizationId` | `OrganizationMemberSource \| null` |
+| `client.memberSources.upsertOrganizationMemberSource({ path, payload })` | `PUT /organizations/:organizationId/member-source` | `path.organizationId`, `UpsertOrganizationMemberSourceInput` | `OrganizationMemberSource` |
+| `client.memberSources.bootstrapOrganizationMemberSourceAgent({ path, payload })` | `POST /organizations/:organizationId/member-source/agent/bootstrap` | `path.organizationId`, `BootstrapOrganizationMemberSourceAgentInput` | `BootstrapOrganizationMemberSourceAgentResponse` |
+| `client.memberSources.getOrganizationMemberSourceCsvUploadReadiness({ path })` | `GET /organizations/:organizationId/member-source/csv-upload-readiness` | `path.organizationId` | `CsvUploadReadiness` |
+| `client.memberSources.getOrganizationMemberSourceCsvMapping({ path })` | `GET /organizations/:organizationId/member-source/csv-mapping` | `path.organizationId` | `OrganizationMemberSourceCsvMapping \| null` |
+| `client.memberSources.upsertOrganizationMemberSourceCsvMapping({ path, payload })` | `PUT /organizations/:organizationId/member-source/csv-mapping` | `path.organizationId`, `UpsertOrganizationMemberSourceCsvMappingInput` | `OrganizationMemberSourceCsvMapping` |
+| `client.memberSources.createOrganizationMemberSourceCsvUpload({ path, payload })` | `POST /organizations/:organizationId/member-source/csv-uploads` | `path.organizationId`, `CreateOrganizationMemberSourceCsvUploadInput` | `CreateOrganizationMemberSourceCsvUploadResponse` |
+| `client.memberSources.listOrganizationMemberSyncRuns({ path, urlParams })` | `GET /organizations/:organizationId/member-source/runs` | `path.organizationId`, optional `page`, `pageSize` | `PaginatedOrganizationMemberSyncRuns` |
+| `client.memberSources.listOrganizationMemberSourceCommands({ path, urlParams })` | `GET /organizations/:organizationId/member-source/commands` | `path.organizationId`, optional `page`, `pageSize` | `PaginatedOrganizationMemberSourceCommands` |
+| `client.memberSources.triggerOrganizationMemberSync({ path, payload })` | `POST /organizations/:organizationId/member-source/sync` | `path.organizationId`, `TriggerOrganizationMemberSyncInput` | `OrganizationMemberSyncRun` |
+
+### Vouchers
+
+| Client method | Route | Request | Returns |
+| --- | --- | --- | --- |
+| `client.vouchers.getOrganizationVoucherProvider({ path })` | `GET /organizations/:organizationId/voucher-provider` | `path.organizationId` | `OrganizationVoucherProvider \| null` |
+| `client.vouchers.upsertOrganizationVoucherProvider({ path, payload })` | `PUT /organizations/:organizationId/voucher-provider` | `path.organizationId`, `UpsertOrganizationVoucherProviderInput` | `OrganizationVoucherProvider` |
+| `client.vouchers.requestVoucherIssue({ path, payload })` | `POST /organizations/:organizationId/vouchers/issue` | `path.organizationId`, `RequestVoucherIssueInput` | `OrganizationVoucherCommand` |
+| `client.vouchers.pollOnsiteVoucherCommand({ path })` | `POST /organizations/:organizationId/onsite-voucher-commands/poll` | `path.organizationId` | `OnsiteVoucherCommand \| null` |
+| `client.vouchers.completeOnsiteVoucherCommand({ path, payload })` | `POST /organizations/:organizationId/onsite-voucher-commands/:commandId/complete` | `path.organizationId`, `path.commandId`, `CompleteOnsiteVoucherCommandInput` | `OrganizationVoucherCommand` |
+
+### Onsite Calls
+
+| Client method | Route | Request | Returns |
+| --- | --- | --- | --- |
+| `client.onsiteCalls.callOnsiteResource({ path, payload })` | `POST /organizations/:organizationId/onsite-calls` | `OnsiteResourceCallRequest` for member create/update/renew/lookup or voucher issue | `OnsiteResourceCallResponse` |
+
+### Onsite Agents
+
+| Client method | Route | Request | Returns |
+| --- | --- | --- | --- |
+| `client.onsiteAgents.heartbeatOnsiteAgent({ payload })` | `POST /onsite-agent/heartbeat` | `OnsiteAgentHeartbeatInput` | `OrganizationMemberSourceAgent` |
+| `client.onsiteAgents.pollOnsiteAgentCommand({})` | `POST /onsite-agent/commands/poll` | none | `OnsiteAgentCommand \| null` |
+| `client.onsiteAgents.pollOnsiteAgentMemberCreateCommand({})` | `POST /onsite-agent/member-commands/poll` | none | `OnsiteAgentMemberCreateCommand \| null` |
+| `client.onsiteAgents.pollOnsiteAgentMemberRenewalCommand({})` | `POST /onsite-agent/member-renewal-commands/poll` | none | `OnsiteAgentMemberRenewalCommand \| null` |
+| `client.onsiteAgents.completeOnsiteAgentRun({ path, payload })` | `POST /onsite-agent/runs/:runId/complete` | `path.runId`, `OnsiteAgentCompleteRunInput` | `OrganizationMemberSyncRun` |
+| `client.onsiteAgents.completeOnsiteAgentMemberCreate({ path, payload })` | `POST /onsite-agent/member-commands/:commandId/complete` | `path.commandId`, `OnsiteAgentCompleteMemberCreateInput` | `OrganizationMemberSourceCommand` |
+| `client.onsiteAgents.completeOnsiteAgentMemberRenewal({ path, payload })` | `POST /onsite-agent/member-renewal-commands/:commandId/complete` | `path.commandId`, `OnsiteAgentCompleteMemberRenewalInput` | `OrganizationMemberSourceCommand` |
+
+### Guests
+
+| Client method | Route | Request | Returns |
+| --- | --- | --- | --- |
+| `client.guests.listGuests({ path, urlParams })` | `GET /organizations/:organizationId/guests` | `path.organizationId`, optional paging and filters `urlParams` | `PaginatedGuests` |
+| `client.guests.createGuest({ path, payload })` | `POST /organizations/:organizationId/guests` | `path.organizationId`, `CreateGuestInput` | `Guest` |
+| `client.guests.updateGuest({ path, payload })` | `PATCH /organizations/:organizationId/guests/:guestId` | `path.organizationId`, `path.guestId`, `UpdateGuestInput` | `Guest` |
+| `client.guests.deleteGuest({ path, payload })` | `DELETE /organizations/:organizationId/guests/:guestId` | `path.organizationId`, `path.guestId`, `DeletePayload` | `void` |
+
+### Service Clients
+
+| Client method | Route | Request | Returns |
+| --- | --- | --- | --- |
+| `client.serviceClients.listServiceClients({ urlParams })` | `GET /service-clients` | optional `page`, `pageSize` | `PaginatedServiceClients` |
+| `client.serviceClients.createServiceClient({ payload })` | `POST /service-clients` | `CreateServiceClientInput` | `{ client: ServiceClient; privateKey: string }` |
+| `client.serviceClients.updateServiceClient({ path, payload })` | `PATCH /service-clients/:serviceClientId` | `path.serviceClientId`, `UpdateServiceClientInput` | `{ client: ServiceClient; privateKey?: string }` |
+
+## Type Exports
+
+The package re-exports the shared contract types, so you can import payload and response types directly:
+
+```ts
+import type {
+  CreateMemberInput,
+  MemberResponse,
+  OrganizationMembersListResponse,
+} from "@spoketech/hub-client";
+```