@genlobe/mcp-server 3.1.8 → 3.3.0

package/dist/index.js

@@ -64,8 +64,13 @@ There are TWO types of authentication contexts:
 - These endpoints ARE for building end-user frontends
 
 ## API Key Types
-- \`pk_live_*\`: Public key - safe to expose in frontend code (LIMITED to auth endpoints only)
-- \`sk_live_*\`: Secret key - backend only, never expose (FULL API access)
+
+- \`pk_live_*\`: Public key — safe to expose in frontend code.
+  - **By itself** (no JWT) the key only unlocks \`/v1/auth/*\` (register, login, refresh, logout, me, forgot-password, reset-password). These are the seven scopes auto-assigned to public keys.
+  - **Combined with an end-user JWT** returned by \`/v1/auth/login\`, the same public key unlocks the full end-user API: \`/v1/user/agents/*\`, \`/v1/entity/records/*\`, \`/v1/plans\`, \`/v1/billing/*\`, \`/v1/users/me\`, etc. Once the JWT is in play, the JWT carries end-user identity and the public key just keeps verifying the tenant context.
+  - Restricted by an Origin allowlist (configured per key) and per-IP rate limits.
+
+- \`sk_live_*\`: Secret key — backend-only, never expose. Required for server-to-server work that no end-user JWT can cover: defining entity schemas (\`/v1/entity/schemas/*\`), bulk record operations (\`/v1/entity/records/bulk\`, \`/v1/entity/records/search\`), webhooks, batch jobs, and other admin tooling on the tenant's own server.
 
 ## API Key Organization Scope (B2B2C)
 
@@ -102,6 +107,38 @@ If you're building a frontend application for end-users, you should:
 2. Use the public API key (pk_live_*) for client-side requests
 3. Include X-API-Key header in ALL requests
 4. After login, also include Authorization: Bearer <jwt> for authenticated requests
+
+## End-User App Flow (the canonical two-phase pattern)
+
+A common confusion: the public key looks restricted to \`/v1/auth/*\`, so developers assume they need to ship the secret key in their frontend to call agents or records. They don't. The pattern is two phases:
+
+\`\`\`
+[Tenant's app frontend in the user's browser]
+  │
+  │ Phase 1 — auth gateway (public key alone is enough)
+  │ X-API-Key: pk_live_xxx
+  ▼
+POST /v1/auth/register   ─┐
+POST /v1/auth/login       ├─ returns { access_token (JWT), refresh_token, user }
+POST /v1/auth/refresh    ─┘
+  │
+  │ Phase 2 — end-user features (public key + JWT)
+  │ X-API-Key: pk_live_xxx
+  │ Authorization: Bearer <end-user JWT>
+  ▼
+GET  /v1/user/agents/available
+POST /v1/user/agents/{id}/chat
+GET/POST/PUT/DELETE /v1/entity/records/...     ← custom-entity records as your app's DB
+GET  /v1/plans
+POST /v1/billing/checkout
+GET  /v1/users/me
+\`\`\`
+
+The \`sk_live_*\` key never reaches the browser. It lives only on the tenant's own server, used for:
+- defining entity schemas (\`/v1/entity/schemas/*\`),
+- bulk record operations (\`/v1/entity/records/bulk\`, \`/search\`),
+- receiving webhooks from the platform,
+- cron jobs and admin tooling.
 `,
     base_url: API_URL,
     documentation_urls: {
@@ -787,7 +824,7 @@ const END_USER_ENDPOINTS = {
         ]
     },
     billing: {
-        description: "Billing operations - checkout, plan changes, cancellation. All endpoints require SECRET key (sk_live_*) only.",
+        description: "Billing operations. Two flavors:\n\n- **Tier 1 (legacy / platform-level)**: endpoints under /v1/billing/* use the platform's Stripe and a SECRET key (sk_live_*) only. They were originally for Genlobe → Tenant billing and a since-superseded Tier 2 prototype; keep using them for tenant-internal flows.\n\n- **Tier 3 (Organization → end-user, Epic #209)**: each Organization runs its OWN Stripe (BYO key). End-users subscribe via /v1/organizations/{org_id}/billing/* (api key + JWT + active OrganizationMember). The Org's plan catalog is read via the public /v1/organizations/{org_id}/plans (api key only — no JWT). See the master spec at specs/features/billing/three-tier-billing.spec.md.",
         endpoints: [
             {
                 method: "GET",
@@ -880,6 +917,91 @@ const END_USER_ENDPOINTS = {
                     total_invoices: "number"
                 },
                 note: "Returns 404 if organization not found or doesn't belong to tenant."
+            },
+            // ---------------------------------------------------------------
+            // Tier 3 endpoints (Epic #209). Each Organization runs its OWN
+            // Stripe (BYO key). These run against the org's Stripe, not the
+            // platform's, and require an active OrganizationMember of the path's
+            // org. Plans are sold by the Organization to its end-users.
+            // ---------------------------------------------------------------
+            {
+                method: "GET",
+                path: "/v1/organizations/{organization_id}/plans",
+                summary: "List the Organization's active plans (Tier 3) — public to anonymous visitors of the org's app",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: false },
+                response: {
+                    items: "array of OrganizationPlan: id (uuid), organization_id (uuid), name (string), slug (string), description (string | null), price_amount (decimal), currency (ISO-4217), billing_interval ('month' | 'year'), stripe_product_id (string | null), stripe_price_id (string | null), stripe_price_id_yearly (string | null), features (array of strings), limits (object<string, int | null>), is_active (boolean), created_at (ISO datetime), updated_at (ISO datetime)",
+                    total: "number"
+                },
+                note: "Tenant-scoped: returns 404 if the Organization doesn't belong to the API key's tenant (no existence leak across tenants). Only plans with is_active=true and stripe_price_id != null are returned — use one of those plan ids when calling /billing/checkout-session.",
+                example_request: `GET /v1/organizations/660e8400-e29b-41d4-a716-446655440001/plans`
+            },
+            {
+                method: "POST",
+                path: "/v1/organizations/{organization_id}/billing/checkout-session",
+                summary: "Start a Stripe Checkout subscription flow for the calling end-user against an Org plan (Tier 3)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    plan_id: "uuid (required) — OrganizationPlan id (NOT a Stripe price id). Get it from /v1/organizations/{organization_id}/plans.",
+                    success_url: "string url (required) — Stripe redirects here on success.",
+                    cancel_url: "string url (required) — Stripe redirects here if the user cancels."
+                },
+                response: {
+                    checkout_url: "string — Stripe-hosted Checkout URL (redirect the user here).",
+                    session_id: "string — Stripe Checkout session id (cs_*)."
+                },
+                errors: {
+                    "403": "Caller is not an active OrganizationMember of the path's org.",
+                    "404": "Plan not found / belongs to a different org / inactive (collapsed to the same 404 to avoid cross-org existence leaks).",
+                    "409": "Plan has no stripe_price_id yet OR the Organization has no Stripe configured (the Org Owner must finish setup first)."
+                },
+                note: "The caller becomes the end-user customer in the Organization's Stripe account, not in the platform's. The actual Subscription row is created by the webhook handler after Stripe fires checkout.session.completed.",
+                example_request: `{
+  "plan_id": "770e8400-e29b-41d4-a716-446655440002",
+  "success_url": "https://claude.example.com/billing/success?cs={CHECKOUT_SESSION_ID}",
+  "cancel_url": "https://claude.example.com/pricing"
+}`
+            },
+            {
+                method: "POST",
+                path: "/v1/organizations/{organization_id}/billing/customer-portal-session",
+                summary: "Open a Stripe Customer Portal session for the calling end-user (Tier 3, manage / cancel)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    return_url: "string url (required) — Stripe redirects here when the user closes the Portal."
+                },
+                response: {
+                    portal_url: "string — Stripe-hosted Customer Portal URL."
+                },
+                errors: {
+                    "403": "Caller is not an active OrganizationMember of the path's org.",
+                    "409": "Caller has no Subscription / no Stripe customer for this Organization yet, OR the Organization has no Stripe configured."
+                },
+                note: "Portal allowed actions (cancel / update payment method / etc.) are configured by the Organization Owner in their own Stripe Dashboard."
+            },
+            {
+                method: "GET",
+                path: "/v1/organizations/{organization_id}/billing/subscription",
+                summary: "Read the calling end-user's current subscription in this Organization (Tier 3)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: {
+                    id: "uuid",
+                    organization_id: "uuid",
+                    user_id: "uuid",
+                    plan_id: "uuid | null",
+                    status: "string | null — Stripe Subscription.status (active, past_due, canceled, …)",
+                    billing_cycle: "string — 'monthly' or 'yearly'",
+                    current_period_start: "ISO datetime | null",
+                    current_period_end: "ISO datetime | null",
+                    cancel_at_period_end: "boolean",
+                    canceled_at: "ISO datetime | null",
+                    trial_start: "ISO datetime | null",
+                    trial_end: "ISO datetime | null"
+                },
+                errors: {
+                    "403": "Caller is not an active OrganizationMember of the path's org.",
+                    "404": "Caller has no Subscription for this Organization yet."
+                }
             }
         ]
     },
@@ -1026,6 +1148,29 @@ const END_USER_ENDPOINTS = {
                     error: "string | null"
                 },
                 note: "Returns 402 Payment Required if usage limits exceeded."
+            },
+            {
+                method: "GET",
+                path: "/v1/organizations/{organization_id}/usage",
+                summary: "Get aggregate usage for one Organization in the queried period",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                query_params: {
+                    period_start: "ISO datetime (optional) - Inclusive start of the aggregation window (UTC). Defaults to the current calendar month.",
+                    period_end: "ISO datetime (optional) - Exclusive end of the aggregation window (UTC). Must be supplied together with period_start.",
+                },
+                response: {
+                    organization_id: "uuid",
+                    organization_name: "string | null - Human-readable name from organizations row, null if the org row was deleted",
+                    organization_slug: "string | null",
+                    period_start: "ISO datetime - resolved window start",
+                    period_end: "ISO datetime - resolved window end",
+                    messages_count: "number - Sum of messages_count across plan_usages rows for the org in the period",
+                    tokens_count: "number - Sum of tokens_count (input + output)",
+                    input_tokens_count: "number",
+                    output_tokens_count: "number",
+                    cost_usd: "string - Decimal as string (e.g. '12.345600')",
+                },
+                note: "Auth requires the caller to be an active OrganizationMember of the path's org. Returns a zero row when the org had no activity in the period, so callers can always render a header without a 404 fallback. Read-only — does not consume usage.",
             }
         ]
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genlobe/mcp-server",
-  "version": "3.1.8",
+  "version": "3.3.0",
   "description": "MCP Server for GenLobe SaaS API - Provides AI assistants with comprehensive API documentation for building frontend applications",
   "main": "dist/index.js",
   "bin": {