@ekzs/cli 0.2.0

package/skills/ekz-payment-core-architecture/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: ekz-payment-core-architecture
+description: >-
+  Provider-agnostic payment architecture: PaymentRequest, PaymentAttempt,
+  ProviderTransaction, WebhookEvent, LedgerEntry, FulfillmentAction,
+  Entitlement, BillingCycle, UsageRecord, state machines, idempotency, and
+  provider boundaries.
+---
+
+# Payment Core Architecture
+
+Use this skill before adding any payment flow. It teaches the reusable payment domain that sits above e-Kwanza or any other provider.
+
+## Core idea
+
+Treat e-Kwanza as a one-time payment rail. Build a clean local payment domain on top of it.
+
+Products, invite/ticket sales, subscriptions, and overage all compose the same primitives:
+
+```text
+business object -> PaymentRequest -> PaymentAttempt -> ProviderTransaction
+                -> WebhookEvent -> LedgerEntry -> FulfillmentAction/Entitlement
+```
+
+## Primitives
+
+`PaymentRequest`
+
+The business claim to collect money. It belongs to an order, ticket reservation, subscription cycle, invoice, or overage charge.
+
+`PaymentAttempt`
+
+One concrete try to collect a request through a provider and rail. A request may have multiple attempts.
+
+`ProviderTransaction`
+
+The provider's identifiers, raw response, operation code, reference, QR payload, expiration, and correlation IDs.
+
+`WebhookEvent`
+
+Raw callback plus normalized status, event ID, dedupe status, processing status, and error details.
+
+`LedgerEntry`
+
+Append-only internal financial/audit movement: requested, authorized, paid, failed, expired, settled, credited, adjusted.
+
+`FulfillmentAction`
+
+The domain side effect to run after payment succeeds: ship order, issue ticket, extend entitlement, settle overage.
+
+`Entitlement`
+
+The access or ownership created by payment: plan access, quota, license, ticket ownership, invite validity.
+
+`BillingCycle`
+
+A local recurring period with start/end, due date, grace window, retry state, and charge request.
+
+`UsageRecord`
+
+An idempotent metered event that can be aggregated into overage charges.
+
+## State machines
+
+Keep provider states separate from local business states.
+
+```text
+PaymentRequest: pending -> paid | failed | expired | canceled
+PaymentAttempt: created -> provider_pending -> succeeded | failed | expired
+WebhookEvent: received -> processing -> processed | ignored | failed
+FulfillmentAction: pending -> completed | failed | compensated
+Entitlement: inactive -> trialing | active | grace | past_due | suspended | canceled
+BillingCycle: open -> invoiced -> paid | past_due | closed
+```
+
+Use the target app's existing enum names if they already exist. Preserve the concepts, not the spelling.
+
+## Provider boundary
+
+Business code should not call e-Kwanza directly. Put the provider behind a small adapter:
+
+```typescript
+type CreatePaymentAttemptInput = {
+  amountAoa: number;
+  rail: "gpo" | "emis_ref" | "ticket";
+  correlationId: string;
+  phoneNumber?: string;
+  metadata?: Record<string, unknown>;
+};
+
+type PaymentProvider = {
+  createAttempt(input: CreatePaymentAttemptInput): Promise<ProviderTransaction>;
+  normalizeWebhook(body: unknown, headers: Headers): Promise<NormalizedPaymentEvent>;
+};
+```
+
+Domain handlers consume local `PaymentRequest` and normalized events, not raw provider payloads.
+
+## Invariants
+
+- Payment collection is not business fulfillment.
+- Compute amount server-side from the domain object.
+- Persist the local request/attempt before creating or exposing provider instructions.
+- Store all provider identifiers returned by the provider.
+- Webhook processing must be idempotent.
+- A duplicate paid event must not duplicate fulfillment, ticket issuance, entitlement extension, or usage settlement.
+- Raw provider statuses must be normalized before domain logic sees them.
+- Ledger entries should be append-only where possible.
+- Retrying payment should create or update a payment attempt, not duplicate the business request.
+
+## Test contracts
+
+Every payment flow should have tests for:
+
+- paid webhook performs exactly one domain side effect
+- duplicate paid webhook is harmless
+- failed/expired webhook leaves a recoverable state
+- amount cannot be changed from the client
+- provider callback without a known local payment is stored or rejected safely
+- retry creates a new attempt or intentional update without double fulfillment
+

package/skills/ekz-sdk-cli/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: ekz-sdk-cli
+description: >-
+  @ekzs/connect TypeScript SDK and @ekzs/cli — healthCheck, createPayment, webhooks,
+  ekz doctor, scan, fix, agent commands.
+---
+
+# @ekzs/connect SDK + CLI
+
+**Agent limit:** in-scope for edits. Unrelated code is read-only context only.
+
+## SDK install
+
+```bash
+npm install @ekzs/connect
+# monorepo: file:packages/sdk
+```
+
+```typescript
+import { EkzConnect, configFromEnv, normalizeWebhookPayload, verifyTicketSignature } from "@ekzs/connect";
+
+const client = new EkzConnect(configFromEnv()!);
+await client.healthCheck();
+await client.createPayment("gpo", { amountAoa, merchantTransactionId, phoneNumber });
+```
+
+Rails: `gpo` | `emis_ref` | `ticket`
+
+Model env: `EKZ_AGENT_MODEL=composer-2.5-fast` → `composer-2.5` + `fast: true`
+
+## CLI commands
+
+| Command | Purpose |
+|---------|---------|
+| `ekz doctor` | Validate `.env`, live OAuth (free) |
+| `ekz scan` | Common integration mistakes (free) |
+| `ekz webhook <url>` | POST sample payload (free) |
+| `ekz agent` | Local coding agent, edits repo (CURSOR_API_KEY) |
+| `ekz fix` | Auto-audit + fix integration |
+| `ekz ask` | Remote Q&A only (EKZ_AGENT_API_KEY) |
+
+Modes: `--mode agent` (default) | `--mode plan` | `--mode ask`. Shorthand: `--plan` = plan mode.
+In the REPL: `/help`, `/mode agent|plan|ask`, `/doctor`, `/scan`, `/lang`, `/save`, `/resume`.
+
+```bash
+export CURSOR_API_KEY=crsr_...
+ekz                    # interactive REPL (agent mode)
+ekz --mode plan        # plan before edits
+ekz --mode ask         # remote Q&A, no edits
+ekz fix                # full integration pass
+ekz agent --resume     # continue .ekz/session.json
+```
+
+### Windows / PowerShell
+
+Run the CLI with `.\ekz`, `npx ekz`, or global `ekz` after `npm run setup:cli`.
+
+When the **local agent** runs shell commands, Ekz detects the terminal at launch (Cursor settings → Git Bash → Windows PowerShell default) and injects matching rules into every turn.
+
+- Use `curl.exe -s "http://localhost:3000/..."` — not bare `curl` (PowerShell alias).
+- Prefer `ekz doctor`, `ekz health`, `ekz webhook <url>` over manual HTTP curls.
+- Avoid bash-only pipes and `/dev/null` unless invoking Git Bash explicitly.
+
+## Agent skills
+
+Bundled in `packages/cli/skills/`. Cursor IDE: `.cursor/skills/` (same content).
+
+Orchestrator: **ekz-connect** — routes to sub-skills by problem type.
+
+## Package layout
+
+```
+packages/sdk/     @ekzs/connect
+packages/cli/     @ekzs/cli
+packages/cli/skills/
+```
+
+## Server agent API
+
+`POST /api/developers/agent` — remote ask with redacted doctor context (Composer 2.5 Fast).
+
+Local file edits require **`ekz agent`**, not the browser demo panel.

package/skills/ekz-subscription-billing/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: ekz-subscription-billing
+description: >-
+  Product-agnostic subscription billing over one-time payment rails: local
+  billing cycles, recurring payment requests, grace periods, retries, dunning,
+  entitlement extension, suspension, and internal reference patterns.
+---
+
+# Subscription Billing
+
+Use this skill for recurring access, memberships, SaaS plans, renewals, trials, grace periods, dunning, and entitlement extension.
+
+## Core idea
+
+e-Kwanza has no native subscription API. A subscription is a local billing lifecycle that creates one-time `PaymentRequest`s when cycles are due.
+
+The internal reference implementation proves this pattern, but its plans, table names, routes, and UI are examples only.
+
+## Pattern
+
+```text
+SubscriptionAccount -> BillingCycle -> PaymentRequest -> PaymentAttempt
+                    -> paid webhook -> extend Entitlement
+                    -> failed/expired -> grace/past_due/suspend
+```
+
+## Concepts
+
+- Subscription account: user, team, tenant, merchant, organization.
+- Plan/product: app-owned catalog and pricing.
+- Billing cycle: period start/end, due date, grace deadline, retry state.
+- Billing request: the one-time charge for a specific cycle.
+- Payment attempt: one e-Kwanza provider attempt for that request.
+- Entitlement: access granted by trial, paid cycle, grace, or cancellation policy.
+- Scheduler: job/cron/queue that issues due requests and expires old ones.
+
+## Lifecycle
+
+1. Select subscriptions whose trial has ended or whose next cycle is due.
+2. Create or reuse the cycle's billing request.
+3. Create a one-time provider attempt through the provider adapter.
+4. Move the subscription into grace or pending-payment state according to policy.
+5. On normalized `paid`, mark request paid, advance next due date, and extend entitlement.
+6. On normalized `failed`, retry or move to `past_due`.
+7. On normalized `expired` after grace, suspend or cancel entitlement.
+
+## Minimal persistence
+
+Use existing models where possible. Add only missing concepts:
+
+```text
+subscription/account:
+  plan_or_product_id
+  status
+  interval
+  trial_ends_at
+  next_due_at
+  grace_ends_at
+  entitlement_state
+  preferred_payment_rail
+  payer_phone
+
+billing_cycle/request:
+  subscriber_id
+  cycle_anchor
+  period_start
+  period_end
+  due_at
+  amount_aoa
+  status
+  payment_request_id
+  metadata
+```
+
+Names are illustrative. Preserve the target app's vocabulary.
+
+## Invariants
+
+- Do not hardcode internal reference-app plan slugs, prices, or intervals.
+- Compute price server-side from the app's catalog.
+- Use a unique key per subscriber and billing cycle.
+- Payment method changes for a pending cycle should update/retry intentionally, not create duplicate cycle requests.
+- Entitlement changes happen from normalized payment events, not raw provider payloads.
+- Trials do not issue charges until policy says the first paid cycle is due.
+- Grace, retry, dunning, and suspension are app policy, not e-Kwanza behavior.
+- Subscription renewal and overage billing can share payment primitives but should remain separate domain flows.
+
+## Scheduler
+
+Use the target app's normal background mechanism:
+
+- cron endpoint
+- queue worker
+- scheduled function
+- database job
+- admin/manual retry command
+
+The scheduler should issue due billing requests, send reminders, expire old pending requests, retry according to policy, and transition accounts through grace, past_due, suspended, or canceled.
+
+## Internal case study
+
+The internal subscription reference maps the generic pattern like this:
+
+- Subscriber: tenant.
+- Billing request: `billing_payment_requests`.
+- Provider label: `ekwanza_subscription`.
+- Scheduler: internal e-Kwanza billing cycle route.
+- Webhook branch: shared e-Kwanza URL routed to billing after public payments.
+- Cycle behavior: local due dates, grace, reminders, paid/failed/canceled transitions.
+
+Use it to understand lifecycle structure. Do not copy its schema or plan catalog unless you are working inside that app.
+
+## Tests
+
+- first paid cycle extends entitlement
+- duplicate paid webhook does not extend twice
+- failed payment enters retry or past_due policy
+- expired request after grace suspends/cancels correctly
+- plan change does not create duplicate cycle requests
+- scheduler skips active trial accounts until due

package/skills/ekz-ticket-invite-selling/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: ekz-ticket-invite-selling
+description: >-
+  Ticket and invite selling architecture: reservation windows, inventory
+  locking, invite ownership, QR/code issuance, release on expiry, paid-only
+  issuance, and duplicate-webhook safety.
+---
+
+# Ticket / Invite Selling
+
+Use this skill for selling event tickets, invitation passes, access codes, QR tickets, memberships with invite tokens, or limited-capacity entry.
+
+Do not confuse this with the e-Kwanza `ticket` rail. The e-Kwanza Ticket API is a provider payment rail. This skill is about the business object being sold.
+
+## Pattern
+
+```text
+TicketReservation -> PaymentRequest -> PaymentAttempt
+                  -> paid webhook -> IssueTicket/Invite
+                  -> failed/expired/timeout -> ReleaseReservation
+```
+
+## Concepts
+
+- Inventory: total capacity, available count, per-type capacity, per-user limits.
+- Reservation: temporary hold with expiration.
+- Payment request: the reservation's charge.
+- Issued ticket/invite: final owned asset after payment.
+- QR/code: app-generated access credential, not proof of payment by itself.
+- Check-in/redemption: separate from payment collection.
+
+## Reservation rules
+
+- Create a reservation before taking payment when inventory is scarce.
+- Give the reservation a short expiration window.
+- Do not issue the final ticket/invite until payment is paid.
+- Release reservation on failed, expired, canceled, or timeout.
+- A retry may reuse a valid reservation or create a new one by explicit policy.
+
+## Issuance rules
+
+Issue exactly once after a normalized paid event:
+
+```text
+paid payment -> lock reservation -> create issued ticket/invite -> mark fulfilled
+```
+
+The issued ticket/invite should store owner, event/product, status, QR/code hash, issuance time, and redemption state.
+
+## QR and invite codes
+
+- Generate QR/invite credentials locally.
+- Store hashes or signed tokens according to the app's security model.
+- Do not treat provider QR/reference data as the final event ticket unless the product intentionally uses it as the access credential.
+
+## Tests
+
+- reservation expires and stock is released
+- paid event issues exactly one ticket/invite
+- duplicate paid webhook does not issue duplicates
+- failed payment releases reservation
+- sold-out inventory blocks new reservations
+- QR/check-in cannot be used before issuance
+

package/skills/ekz-webhook-normalization/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: ekz-webhook-normalization
+description: >-
+  Webhook normalization architecture: parse GPO, EMIS reference, and Ticket
+  callbacks into shared internal events, dedupe, persist, and route to product,
+  ticket, subscription, or overage handlers.
+---
+
+# Webhook Normalization
+
+Webhook code should normalize provider callbacks before touching business logic.
+
+## Pipeline
+
+```text
+raw provider callback
+  -> verify provider authenticity
+  -> normalize status and identifiers
+  -> persist WebhookEvent idempotently
+  -> resolve local PaymentAttempt/PaymentRequest
+  -> route to domain handler
+  -> mark event processed or failed
+```
+
+## Normalized event
+
+```typescript
+type NormalizedPaymentEvent = {
+  provider: "ekwanza";
+  rail: "gpo" | "emis_ref" | "ticket" | "unknown";
+  status: "pending" | "paid" | "failed" | "expired";
+  rawStatus: number | string | null;
+  eventId: string;
+  merchantTransactionId?: string;
+  providerOperationId?: string;
+  operationCode?: string;
+  code?: string;
+  occurredAt: string;
+  raw: unknown;
+};
+```
+
+## Status mapping
+
+| Provider value | Internal status |
+|----------------|-----------------|
+| `0` | `pending` |
+| `1` | `paid` |
+| `3` | `expired` |
+| `4`, `5` | `failed` |
+
+Normalize string numbers before comparison.
+
+## Idempotency
+
+Durably register the event before side effects. Event IDs should combine stable provider identifiers and status:
+
+```text
+ekwanza:{merchantTransactionId}:{status}
+ekwanza-ticket:{operationCode}:{code}:{status}
+```
+
+A duplicate event must not double-fulfill, double-issue, double-extend, or double-settle anything.
+
+## Routing
+
+Route normalized events by local payment ownership:
+
+- product/order/invoice payment -> product fulfillment handler
+- ticket/invite reservation -> ticket issuance/release handler
+- subscription cycle request -> subscription entitlement handler
+- overage charge -> usage settlement handler
+
+The webhook route itself should not contain all business behavior.
+
+## Ticket HMAC
+
+Ticket-like callbacks must verify `x-signature` using the provider adapter. Production behavior must fail closed.
+
+## Tests
+
+- GPO paid normalizes to paid
+- Ticket paid normalizes to paid after HMAC verification
+- string status `"1"` and numeric status `1` are equivalent
+- duplicate event is recorded once and side effects run once
+- unknown local payment is handled safely
+- invalid Ticket signature does not reach domain handlers
+