@spoketech/hub-client 0.1.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@spoketech/hub-client",
+  "version": "0.1.0",
+  "description": "Effect-native client for the Spoke Hub API",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Spoke-Technologies/spoke-hub.git",
+    "directory": "packages/client"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "skills"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsup",
+    "prepack": "npm run build",
+    "check-types": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.96.0",
+    "effect": "^3.21.0"
+  },
+  "devDependencies": {
+    "@spoke-hub/config": "workspace:*",
+    "@types/node": "^22.13.14",
+    "tsup": "^8.5.1",
+    "typescript": "^5"
+  }
+}

package/skills/spoke-hub-client/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: spoke-hub-client
+description: Use when Codex needs to integrate with, explain, troubleshoot, or update code that uses the `@spoketech/hub-client` npm package, including promise-based usage, Effect-based usage, service-client authentication, endpoint selection, request object shapes, or mapping business actions to client methods.
+---
+
+# Spoke Hub Client
+
+## Overview
+
+Use this skill for application code that consumes `@spoketech/hub-client`. Prefer the promise-based client for normal async code and use the raw Effect client only when the surrounding code already uses Effect.
+
+## Workflow
+
+1. Read `../../README.md` for the current install instructions, auth patterns, and full endpoint reference.
+2. If you need the exact helper signatures, inspect `../../dist/client.d.ts`.
+3. If you need the exact contract or type names, inspect `../../dist/contracts.d.ts`.
+4. Match the user to the right entrypoint:
+   `makePromiseHubApiClient` for unsigned or separately-authenticated access.
+   `makePromiseServiceHubApiClient` for `clientId` plus `privateKey`.
+   `makeHubApiClient` or `makeServiceHubApiClient` only when the caller is already Effect-native.
+5. Build calls with the standard request object shape:
+   `path` for route params.
+   `payload` for JSON bodies.
+   `urlParams` for query-string fields.
+   `headers` only for unusual per-request overrides.
+6. Reuse the exported contract types instead of inventing inline request shapes.
+
+## Guidance
+
+- Prefer the promise wrappers in examples unless the user explicitly wants Effect.
+- Keep `baseUrl` at the site origin; the client adds `/api` and targets `/api/v1/...` by default.
+- Do not invent endpoint names. Use the exact group and method names from the README endpoint tables.
+- For member list queries, keep query params in the contract format. Some filters are strings even when they represent page numbers or IDs.
+- For delete/archive operations, remember the API expects `DeletePayload` with `expectedUpdatedAt`.
+
+## References
+
+- Load `../../README.md` for the full endpoint-by-endpoint client reference.
+- Load `references/workflows.md` for common usage patterns and code templates.

package/skills/spoke-hub-client/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Spoke Hub Client"
+  short_description: "Guide Spoke Hub client usage and workflows"
+  default_prompt: "Use $spoke-hub-client to integrate with @spoketech/hub-client in this workspace."

package/skills/spoke-hub-client/references/workflows.md

@@ -0,0 +1,83 @@
+# Spoke Hub Client Workflows
+
+## Choose the Right Client
+
+- Use `makePromiseHubApiClient` when the caller is handling auth outside the package.
+- Use `makePromiseServiceHubApiClient` when the caller has `clientId` and `privateKey`.
+- Use `makePromiseServiceHubApiClient` for server-to-server integrations that should sign every request automatically.
+- Use `makeHubApiClient` or `makeServiceHubApiClient` only when the surrounding application already uses Effect.
+
+## Common Template
+
+```ts
+import { makePromiseHubApiClient } 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!,
+});
+```
+
+## Request Shapes
+
+- Use `path` for route params:
+  `path: { organizationId: "org_123", memberId: "mem_123" }`
+- Use `payload` for bodies:
+  `payload: { firstName: "Jane", lastName: "Smith" }`
+- Use `urlParams` for query strings:
+  `urlParams: { responseMode: "med", page: "1", pageSize: "25" }`
+
+## Common Tasks
+
+- List members:
+
+```ts
+const members = await client.members.listOrganizationMembers({
+  path: { organizationId: "org_123" },
+  urlParams: { responseMode: "med", page: "1", pageSize: "25" },
+});
+```
+
+- Create a member:
+
+```ts
+const member = await client.members.createOrganizationMember({
+  path: { organizationId: "org_123" },
+  payload: {
+    firstName: "Jane",
+    lastName: "Smith",
+    email: "jane@example.com",
+  },
+});
+```
+
+- Trigger a sync:
+
+```ts
+const run = await client.memberSources.triggerOrganizationMemberSync({
+  path: { organizationId: "org_123" },
+  payload: { mode: "delta" },
+});
+```
+
+- Archive a guest:
+
+```ts
+await client.guests.deleteGuest({
+  path: { organizationId: "org_123", guestId: "gst_123" },
+  payload: { expectedUpdatedAt: guest.updatedAt },
+});
+```
+
+## Find the Right Endpoint
+
+Read `../../README.md` and use the Endpoint Reference sections:
+
+- `Auth`
+- `Organizations`
+- `Members`
+- `Member Sources`
+- `Onsite Agents`
+- `Guests`
+- `Service Clients`