@capivv/mcp-server 0.5.24 → 0.5.26

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, ListAppUsersResult, FindUserResult, GrantEntitlementRequest, GrantEntitlementResult, RevokeEntitlementRequest, SetAppleSubscriptionLevelRequest, SetAppleSubscriptionLevelResult } 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;
@@ -109,4 +109,5 @@ export declare class CapivvClient {
         success: boolean;
     }>;
     setAppleSubscriptionLevel(req: SetAppleSubscriptionLevelRequest): Promise<SetAppleSubscriptionLevelResult>;
+    setReviewScreenshot(req: SetReviewScreenshotRequest): Promise<SetReviewScreenshotResult>;
 }

package/dist/client.js

@@ -397,4 +397,8 @@ export class CapivvClient {
         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/create-product.js

@@ -52,6 +52,10 @@ export function registerCreateProductTool(server, client) {
             .boolean()
             .optional()
             .describe('When true (default), opts the subscription into new Apple territories automatically as Apple adds them. SaaS-friendly default.'),
+        apple_review_note: z
+            .string()
+            .optional()
+            .describe('Text written to Apple\'s "App Review Notes" field on the subscription / IAP. Optional — when omitted Capivv writes a sensible default ("This product grants the user the X entitlement..."). Override when App Review needs explicit testing instructions (e.g. a demo account, a way to skip past a paywall).'),
     }, async (args) => {
         const { skip_store_write, ...rest } = args;
         const product = await client.createProduct({

package/dist/tools/index.js

@@ -85,6 +85,7 @@ 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';
@@ -232,4 +233,9 @@ export function registerAllTools(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/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

@@ -262,6 +262,14 @@ export interface CreateProductRequest {
      * adds them. Defaults to true.
      */
     apple_available_in_new_territories?: boolean;
+    /**
+     * V0.5.26 — text written to Apple's "App Review Notes" field on the
+     * subscription / IAP. Optional; when omitted Capivv generates a sensible
+     * default based on product_type + display_name. Override for products
+     * that need explicit testing instructions for the App Review team
+     * (e.g. a demo account, a way to skip past a paywall).
+     */
+    apple_review_note?: string;
 }
 export interface Paywall {
     id: string;
@@ -727,3 +735,17 @@ 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.24",
+  "version": "0.5.26",
   "description": "MCP server for managing Capivv subscription platform via AI assistants",
   "type": "module",
   "bin": {