@capivv/mcp-server 0.5.23 → 0.5.25

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import type { Config } from './config.js';
-import type { App, Product, Entitlement, Offering, Rule, Experiment, ExperimentSummary, AnalyticsOverview, OnboardingResponse, ImportPreviewResponse, CreateAppRequest, CreateEntitlementRequest, CreateProductRequest, CreateOfferingRequest, CreateRuleRequest, ValidateRuleRequest, ValidateRuleResponse, WhoamiResponse, ApiKeyUsageResponse, Paywall, CreatePaywallRequest, UpdatePaywallRequest, PaywallStats, Promotion, CreatePromotionRequest, UpdatePromotionRequest, RescueFlow, CreateRescueFlowRequest, UpdateRescueFlowRequest, RescueStats, PricingStrategy, CreatePricingStrategyRequest, PricingPreviewResult, PricingRecomputeRequest, PricingRecomputeResult, PricingPushResult, PricingChangeRequest, SetCountryPriceOverrideRequest, ExperimentWithVariants, CreateExperimentRequest, UpdateExperimentRequest, UpdateAppRequest, UpdateEntitlementRequest, UpdateOfferingRequest, AutopilotRunResult, SyncSuggestion, SyncSuggestionsCount, TriggerSyncResult, IntegrationSummary, ConnectAppleIntegrationRequest, ConnectAppleIntegrationResult, ConnectGoogleIntegrationRequest, ConnectGoogleIntegrationResult, SetSubscriptionReviewScreenshotRequest, SetSubscriptionReviewScreenshotResult, SubscriptionStateInfo, TouchSubscriptionResult, ProbeSubmissionRequest, ProbeSubmissionResult, SetAppPrivacyUrlRequest, SetAppPrivacyUrlResult, SetIapReviewScreenshotRequest, SetIapReviewScreenshotResult, IapStateInfo, ListAppleSubscriptionsResult, ListAppleIapsResult, DeleteAppleResult } from './types.js';
+import type { App, Product, Entitlement, Offering, Rule, Experiment, ExperimentSummary, AnalyticsOverview, OnboardingResponse, ImportPreviewResponse, CreateAppRequest, CreateEntitlementRequest, CreateProductRequest, CreateOfferingRequest, CreateRuleRequest, ValidateRuleRequest, ValidateRuleResponse, WhoamiResponse, ApiKeyUsageResponse, Paywall, CreatePaywallRequest, UpdatePaywallRequest, PaywallStats, Promotion, CreatePromotionRequest, UpdatePromotionRequest, RescueFlow, CreateRescueFlowRequest, UpdateRescueFlowRequest, RescueStats, PricingStrategy, CreatePricingStrategyRequest, PricingPreviewResult, PricingRecomputeRequest, PricingRecomputeResult, PricingPushResult, PricingChangeRequest, SetCountryPriceOverrideRequest, ExperimentWithVariants, CreateExperimentRequest, UpdateExperimentRequest, UpdateAppRequest, UpdateEntitlementRequest, UpdateOfferingRequest, AutopilotRunResult, SyncSuggestion, SyncSuggestionsCount, TriggerSyncResult, IntegrationSummary, ConnectAppleIntegrationRequest, ConnectAppleIntegrationResult, ConnectGoogleIntegrationRequest, ConnectGoogleIntegrationResult, SetSubscriptionReviewScreenshotRequest, SetSubscriptionReviewScreenshotResult, SubscriptionStateInfo, TouchSubscriptionResult, ProbeSubmissionRequest, ProbeSubmissionResult, SetAppPrivacyUrlRequest, SetAppPrivacyUrlResult, SetIapReviewScreenshotRequest, SetIapReviewScreenshotResult, IapStateInfo, ListAppleSubscriptionsResult, ListAppleIapsResult, DeleteAppleResult, ListAppUsersResult, FindUserResult, GrantEntitlementRequest, GrantEntitlementResult, RevokeEntitlementRequest, SetAppleSubscriptionLevelRequest, SetAppleSubscriptionLevelResult, SetReviewScreenshotRequest, SetReviewScreenshotResult } from './types.js';
 export declare class ApiError extends Error {
     status: number;
     code: string;
@@ -102,4 +102,12 @@ export declare class CapivvClient {
     listAppleIaps(appId: string): Promise<ListAppleIapsResult>;
     deleteAppleSubscription(appleSubscriptionId: string): Promise<DeleteAppleResult>;
     deleteAppleIap(appleIapId: string): Promise<DeleteAppleResult>;
+    listAppUsers(limit?: number, offset?: number): Promise<ListAppUsersResult>;
+    findAppUser(query: string): Promise<FindUserResult>;
+    grantEntitlement(req: GrantEntitlementRequest): Promise<GrantEntitlementResult>;
+    revokeEntitlement(req: RevokeEntitlementRequest): Promise<{
+        success: boolean;
+    }>;
+    setAppleSubscriptionLevel(req: SetAppleSubscriptionLevelRequest): Promise<SetAppleSubscriptionLevelResult>;
+    setReviewScreenshot(req: SetReviewScreenshotRequest): Promise<SetReviewScreenshotResult>;
 }

package/dist/client.js

@@ -378,4 +378,27 @@ export class CapivvClient {
     async deleteAppleIap(appleIapId) {
         return this.delete(`/dashboard/iap/${encodeURIComponent(appleIapId)}`);
     }
+    // ---- V0.5.24 — Issue #2 (Ludmilla) ----
+    async listAppUsers(limit = 50, offset = 0) {
+        return this.get(`/dashboard/users?limit=${limit}&offset=${offset}`);
+    }
+    async findAppUser(query) {
+        return this.get(`/dashboard/users/find?q=${encodeURIComponent(query)}`);
+    }
+    async grantEntitlement(req) {
+        const { user_id, entitlement_id, ...body } = req;
+        return this.post(`/dashboard/users/${encodeURIComponent(user_id)}/entitlements/${encodeURIComponent(entitlement_id)}/grant`, body);
+    }
+    async revokeEntitlement(req) {
+        const { user_id, entitlement_id, reason } = req;
+        return this.post(`/dashboard/users/${encodeURIComponent(user_id)}/entitlements/${encodeURIComponent(entitlement_id)}/revoke`, { reason });
+    }
+    async setAppleSubscriptionLevel(req) {
+        const { apple_subscription_id, level } = req;
+        return this.post(`/dashboard/subscriptions/${encodeURIComponent(apple_subscription_id)}/level`, { level });
+    }
+    async setReviewScreenshot(req) {
+        const { external_id, ...body } = req;
+        return this.post(`/dashboard/products/by-external-id/${encodeURIComponent(external_id)}/review-screenshot`, body);
+    }
 }

package/dist/tools/find-user.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CapivvClient } from '../client.js';
+export declare function registerFindUserTool(server: McpServer, client: CapivvClient): void;

package/dist/tools/find-user.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+export function registerFindUserTool(server, client) {
+    server.tool('capivv_find_user', [
+        'Resolve a Capivv user_id from an external_id or email — primary unblocker for "give Pro to ludmilla@example.com" workflows.',
+        '',
+        'Tries external_id first (exact match — your customer-controlled identifier passed to Capivv.identify). Falls back to email (case-insensitive). Returns `{ user, matched_on: "external_id" | "email" }` so you know which field hit.',
+        '',
+        'Returns `user: null` (no error) when no match is found. Pair with capivv_grant_entitlement to give that user an entitlement.',
+    ].join(' '), {
+        query: z
+            .string()
+            .min(1)
+            .describe('An external_id (exact match) or email address (case-insensitive).'),
+    }, async ({ query }) => {
+        const result = await client.findAppUser(query);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/grant-entitlement.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CapivvClient } from '../client.js';
+export declare function registerGrantEntitlementTool(server: McpServer, client: CapivvClient): void;

package/dist/tools/grant-entitlement.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+export function registerGrantEntitlementTool(server, client) {
+    server.tool('capivv_grant_entitlement', [
+        'Manually grant an entitlement to a specific user — bypassing a purchase.',
+        '',
+        'Common use cases: dev/tester needs Pro for local testing, App Reviewer demo account, comp / VIP grant, support escalation after a refund. Recorded in the audit log with the optional `reason` you supply, so granted access can be tracked for compliance.',
+        '',
+        'Pair with capivv_find_user (resolve user_id from email) and capivv_list_entitlements (find entitlement_id). Set `expires_at` to ISO-8601 for time-limited grants (typical for App Reviewer demos: 30-day window); omit for indefinite (lifetime comp).',
+        '',
+        'Idempotent — granting the same entitlement to the same user updates expiry and reason instead of creating a duplicate.',
+    ].join(' '), {
+        user_id: z.string().describe('Capivv user UUID. Use capivv_find_user to resolve from email/external_id.'),
+        entitlement_id: z.string().describe('Entitlement UUID. Use capivv_list_entitlements to find it.'),
+        expires_at: z
+            .string()
+            .optional()
+            .describe('ISO-8601 expiry (e.g. "2026-08-01T00:00:00Z"). Omit for indefinite grants.'),
+        reason: z
+            .string()
+            .optional()
+            .describe('Free-form audit reason ("App Reviewer demo", "comp for X", "refund support escalation").'),
+    }, async (args) => {
+        const result = await client.grantEntitlement(args);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/index.js

@@ -80,6 +80,12 @@ import { registerProbeSubmissionTool } from './probe-submission.js';
 import { registerSetAppPrivacyUrlTool } from './set-app-privacy-url.js';
 import { registerSetIapReviewScreenshotTool } from './set-iap-review-screenshot.js';
 import { registerGetIapStateTool } from './get-iap-state.js';
+import { registerGrantEntitlementTool } from './grant-entitlement.js';
+import { registerRevokeEntitlementTool } from './revoke-entitlement.js';
+import { registerListUsersTool } from './list-users.js';
+import { registerFindUserTool } from './find-user.js';
+import { registerSetAppleSubscriptionLevelTool } from './set-apple-subscription-level.js';
+import { registerSetReviewScreenshotTool } from './set-review-screenshot.js';
 import { registerListAppleSubscriptionsTool } from './list-apple-subscriptions.js';
 import { registerListAppleIapsTool } from './list-apple-iaps.js';
 import { registerDeleteAppleSubscriptionTool } from './delete-apple-subscription.js';
@@ -215,4 +221,21 @@ export function registerAllTools(server, client) {
     registerListAppleIapsTool(server, client);
     registerDeleteAppleSubscriptionTool(server, client);
     registerDeleteAppleIapTool(server, client);
+    // V0.5.24 — issue #2 (Ludmilla): MCP gaps that forced workarounds in
+    // a real product session.
+    // - grant/revoke entitlement: dev/tester/reviewer/comp/refund flows
+    // - list/find user: resolve user_id from email or external_id (the
+    //   primitive that unblocks "give Pro to ludmilla@example.com")
+    // - set apple subscription level: fix Apple's instant-upgrade UX
+    //   when ASC shows every product at Level 1
+    registerGrantEntitlementTool(server, client);
+    registerRevokeEntitlementTool(server, client);
+    registerListUsersTool(server, client);
+    registerFindUserTool(server, client);
+    registerSetAppleSubscriptionLevelTool(server, client);
+    // V0.5.25 — issue #4: unified review-screenshot upload routing by
+    // product type from Capivv's DB. The two existing tools
+    // (set_subscription_review_screenshot / set_iap_review_screenshot)
+    // remain as escape hatches but their docstrings now redirect here.
+    registerSetReviewScreenshotTool(server, client);
 }

package/dist/tools/list-users.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CapivvClient } from '../client.js';
+export declare function registerListUsersTool(server: McpServer, client: CapivvClient): void;

package/dist/tools/list-users.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+export function registerListUsersTool(server, client) {
+    server.tool('capivv_list_users', [
+        'List app users (the people who use your app, identified via Capivv.identify in the SDK). Paginated.',
+        '',
+        'For finding a single user by email or external_id, prefer capivv_find_user — it does a single targeted lookup instead of paging.',
+    ].join(' '), {
+        limit: z.number().int().min(1).max(200).optional().describe('Max users per page (default 50, max 200).'),
+        offset: z.number().int().min(0).optional().describe('Pagination offset (default 0).'),
+    }, async ({ limit, offset }) => {
+        const result = await client.listAppUsers(limit ?? 50, offset ?? 0);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/revoke-entitlement.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CapivvClient } from '../client.js';
+export declare function registerRevokeEntitlementTool(server: McpServer, client: CapivvClient): void;

package/dist/tools/revoke-entitlement.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+export function registerRevokeEntitlementTool(server, client) {
+    server.tool('capivv_revoke_entitlement', [
+        'Revoke an entitlement from a specific user (the inverse of capivv_grant_entitlement). Use for refunds, expired comps, or when a tester no longer needs access.',
+        '',
+        'Recorded in the audit log with the optional `reason`. Idempotent — revoking an already-revoked entitlement is a no-op.',
+    ].join(' '), {
+        user_id: z.string().describe('Capivv user UUID.'),
+        entitlement_id: z.string().describe('Entitlement UUID to revoke.'),
+        reason: z.string().optional().describe('Free-form audit reason.'),
+    }, async (args) => {
+        const result = await client.revokeEntitlement(args);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/set-apple-subscription-level.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CapivvClient } from '../client.js';
+export declare function registerSetAppleSubscriptionLevelTool(server: McpServer, client: CapivvClient): void;

package/dist/tools/set-apple-subscription-level.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+export function registerSetAppleSubscriptionLevelTool(server, client) {
+    server.tool('capivv_set_apple_subscription_level', [
+        "Set Apple's subscription `groupLevel` (PATCH /v1/subscriptions/{id}). Required for instant-upgrade + proration to work — without it Apple treats every Level-1 product as a crossgrade and the per-pack → Pro upgrade UX breaks.",
+        '',
+        "Apple convention: Level 1 is the most-upgraded tier (e.g. Pro), Level 2/3/... go downward. Within a subscription group, all products at the same level are cross-graded; switching between levels triggers Apple's instant-upgrade + prorate flow.",
+        '',
+        "Get apple_subscription_id from the `store_create.store_product_id` field of capivv_create_product (when product_type is subscription) or from App Store Connect's URL.",
+    ].join(' '), {
+        apple_subscription_id: z
+            .string()
+            .describe('Apple subscription ID (e.g. "6764778053") — NOT the Capivv product UUID.'),
+        level: z
+            .number()
+            .int()
+            .min(1)
+            .describe('Apple groupLevel. 1 = highest tier (e.g. Pro). 2 = next, etc.'),
+    }, async (args) => {
+        const result = await client.setAppleSubscriptionLevel(args);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/tools/set-iap-review-screenshot.js

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 export function registerSetIapReviewScreenshotTool(server, client) {
     server.tool('capivv_set_iap_review_screenshot', [
+        '**Lower-level escape hatch — prefer `capivv_set_review_screenshot` unless you already have the Apple IAP numeric id.** This tool only works for consumables/non-consumables; calling it with a subscription id will silently fail. The unified tool reads product type from Capivv\'s DB and routes correctly.',
+        '',
         'Upload the App Store review screenshot for an in-app purchase (consumable or non-consumable). Mirrors capivv_set_subscription_review_screenshot but uses the IAP endpoint.',
         '',
         'Apple expects 640x920 (or larger) PNG / JPEG. Provide either `image_url` (Capivv backend fetches it via HTTPS) or `image_base64` (raw bytes inline). The backend handles the 3-step Apple flow: reserve → PUT bytes to S3 → PATCH uploaded=true with MD5.',

package/dist/tools/set-review-screenshot.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CapivvClient } from '../client.js';
+export declare function registerSetReviewScreenshotTool(server: McpServer, client: CapivvClient): void;

package/dist/tools/set-review-screenshot.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+export function registerSetReviewScreenshotTool(server, client) {
+    server.tool('capivv_set_review_screenshot', [
+        "**Preferred way to attach an App Store review screenshot to a product.** Single tool that routes to the right Apple endpoint based on Capivv's stored product type — sub vs IAP. Use this instead of capivv_set_subscription_review_screenshot / capivv_set_iap_review_screenshot when you don't already know the product type.",
+        '',
+        'Why it exists: customers with mixed product sets (e.g. 2 auto-renewable subs + 1 lifetime IAP) tripped over the two-tool split — agents reached for the subscription tool for everything, the IAP screenshot silently never uploaded, and Apple rejected the app at review for missing IAP metadata. This unified tool eliminates that class of error: pass the product\'s external_id (e.g. "com.example.pro.lifetime") and Capivv figures out the type.',
+        '',
+        'Apple expects 640x920 PNG/JPEG. Provide image_url (HTTPS, backend fetches up to 10MB) OR image_base64 (raw bytes inline). The backend handles the 3-step Apple flow (reserve → S3 upload → PATCH uploaded=true with MD5).',
+    ].join(' '), {
+        app_id: z
+            .string()
+            .describe('Capivv app UUID. external_id is unique per app, not globally. Get this from capivv_list_apps.'),
+        external_id: z
+            .string()
+            .describe('The product\'s external_id (the identifier you used when creating the product — e.g. "com.example.pro.monthly"). Capivv reads the product type from its DB and routes to the right Apple endpoint.'),
+        image_url: z
+            .string()
+            .optional()
+            .describe('Public HTTPS URL of the screenshot. Mutually exclusive with image_base64.'),
+        image_base64: z
+            .string()
+            .optional()
+            .describe('Base64-encoded raw image bytes. Use for private storage. Mutually exclusive with image_url.'),
+        file_name: z
+            .string()
+            .optional()
+            .describe('Filename Apple stores. Defaults to "screenshot.png".'),
+    }, async (args) => {
+        if (!args.image_url && !args.image_base64) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Provide either image_url (HTTPS) or image_base64 (raw bytes).',
+                    },
+                ],
+            };
+        }
+        const result = await client.setReviewScreenshot(args);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/tools/set-subscription-review-screenshot.js

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 export function registerSetSubscriptionReviewScreenshotTool(server, client) {
     server.tool('capivv_set_subscription_review_screenshot', [
+        '**Lower-level escape hatch — prefer `capivv_set_review_screenshot` unless you already have the Apple subscription numeric id.** This tool only works for auto-renewing subscriptions; calling it with an IAP id will silently fail or upload to the wrong product. The unified tool reads product type from Capivv\'s DB and routes correctly.',
+        '',
         'Upload the App Store review screenshot for a subscription. Apple requires this before an auto-renewing subscription can leave MISSING_METADATA and be submitted for review.',
         '',
         'Apple expects 640x920 (or larger) PNG / JPEG. Provide either `image_url` (Capivv backend fetches it via HTTPS) or `image_base64` (raw bytes inline). The backend handles the 3-step Apple flow: reserve → PUT bytes to S3 → PATCH uploaded=true with MD5.',

package/dist/types.d.ts

@@ -680,3 +680,64 @@ export interface DeleteAppleResult {
     deleted: boolean;
     apple_id: string;
 }
+export interface AppUser {
+    id: string;
+    external_id: string;
+    attributes: Record<string, unknown>;
+    first_seen_at: string;
+    last_seen_at: string;
+    created_at: string;
+}
+export interface ListAppUsersResult {
+    users: AppUser[];
+    total: number;
+}
+export interface FindUserResult {
+    /** The matched user, or null if no user matched the query. */
+    user: AppUser | null;
+    /** Which field matched: "external_id" or "email" — null when no match. */
+    matched_on: 'external_id' | 'email' | null;
+}
+export interface GrantEntitlementRequest {
+    user_id: string;
+    entitlement_id: string;
+    /** ISO-8601 expiry. Omit for indefinite (lifetime comp / dev grant). */
+    expires_at?: string;
+    /** Free-form audit reason (App Reviewer demo / refund / etc.). */
+    reason?: string;
+}
+export interface GrantEntitlementResult {
+    success: boolean;
+    user_id: string;
+    entitlement_id: string;
+    entitlement: string;
+    expires_at?: string;
+}
+export interface RevokeEntitlementRequest {
+    user_id: string;
+    entitlement_id: string;
+    reason?: string;
+}
+export interface SetAppleSubscriptionLevelRequest {
+    apple_subscription_id: string;
+    /** Apple groupLevel — 1 is the highest tier (e.g. Pro), increments downward. */
+    level: number;
+}
+export interface SetAppleSubscriptionLevelResult {
+    apple_subscription_id: string;
+    level: number;
+}
+export interface SetReviewScreenshotRequest {
+    app_id: string;
+    external_id: string;
+    image_url?: string;
+    image_base64?: string;
+    file_name?: string;
+}
+export interface SetReviewScreenshotResult {
+    external_id: string;
+    product_type: 'subscription' | 'consumable' | 'non_consumable';
+    apple_product_id: string;
+    screenshot_id: string;
+    bytes_uploaded: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capivv/mcp-server",
-  "version": "0.5.23",
+  "version": "0.5.25",
   "description": "MCP server for managing Capivv subscription platform via AI assistants",
   "type": "module",
   "bin": {