@capivv/mcp-server 0.5.4 → 0.5.6

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 } 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 } from './types.js';
 export declare class ApiError extends Error {
     status: number;
     code: string;
@@ -91,4 +91,7 @@ export declare class CapivvClient {
     connectAppleIntegration(data: ConnectAppleIntegrationRequest): Promise<ConnectAppleIntegrationResult>;
     connectGoogleIntegration(data: ConnectGoogleIntegrationRequest): Promise<ConnectGoogleIntegrationResult>;
     disconnectIntegration(provider: string): Promise<void>;
+    setSubscriptionReviewScreenshot(data: SetSubscriptionReviewScreenshotRequest): Promise<SetSubscriptionReviewScreenshotResult>;
+    getSubscriptionState(appleSubscriptionId: string): Promise<SubscriptionStateInfo>;
+    touchSubscription(appleSubscriptionId: string): Promise<TouchSubscriptionResult>;
 }

package/dist/client.js

@@ -339,4 +339,15 @@ export class CapivvClient {
     async disconnectIntegration(provider) {
         await this.post(`/dashboard/integrations/${encodeURIComponent(provider)}/disconnect`);
     }
+    // ---- Subscription review screenshot (V0.5.5) ----
+    async setSubscriptionReviewScreenshot(data) {
+        const { apple_subscription_id, ...body } = data;
+        return this.post(`/dashboard/subscriptions/${encodeURIComponent(apple_subscription_id)}/review-screenshot`, body);
+    }
+    async getSubscriptionState(appleSubscriptionId) {
+        return this.get(`/dashboard/subscriptions/${encodeURIComponent(appleSubscriptionId)}/state`);
+    }
+    async touchSubscription(appleSubscriptionId) {
+        return this.post(`/dashboard/subscriptions/${encodeURIComponent(appleSubscriptionId)}/touch`);
+    }
 }

package/dist/tools/create-product.js

@@ -7,6 +7,8 @@ export function registerCreateProductTool(server, client) {
         'Pass `skip_store_write: true` to opt out of the store-side write — only useful when migrating an existing store-side product into Capivv (rare).',
         '',
         'On success the response includes a `store_create` block with the store-side product ID and snapped prices. On store failure the Capivv-side record is rolled back and the verbatim store error is returned.',
+        '',
+        'KNOWN APPLE ISSUE — auto-renewing subscriptions: After this call succeeds, Apple may keep the subscription at MISSING_METADATA even when all metadata is uploaded. This is a known divergence between Apple\'s modern /v1/subscriptions API and its legacy /v1/inAppPurchases mirror. After uploading the review screenshot via capivv_set_subscription_review_screenshot, poll capivv_get_subscription_state — if state stays at MISSING_METADATA for more than a few minutes, call capivv_touch_subscription (best-effort) or have the customer click Save in the App Store Connect web UI.',
     ].join(' '), {
         app_id: z.string().describe('App ID this product belongs to'),
         external_id: z.string().describe('Store product ID (e.g., "com.example.pro_monthly")'),
@@ -69,6 +71,12 @@ function formatStoreCreateSummary(product) {
             lines.push(`  ${sp.currency}: used ${formatCents(sp.actual_cents, sp.currency)} — closest store tier to your ${formatCents(sp.requested_cents, sp.currency)} request.`);
         }
     }
+    if (sc.truncations && sc.truncations.length > 0) {
+        lines.push('Note: Apple length caps on subscription localization clipped the following fields — re-running with shorter values is fine but the existing values above are what was posted.');
+        for (const t of sc.truncations) {
+            lines.push(`  ${t.locale} ${t.field}: shortened from ${t.original_chars} to ${t.truncated_chars} chars (Apple max ${t.limit}).`);
+        }
+    }
     return lines.join('\n');
 }
 function formatCents(cents, currency) {

package/dist/tools/get-subscription-state.d.ts

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

package/dist/tools/get-subscription-state.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+export function registerGetSubscriptionStateTool(server, client) {
+    server.tool('capivv_get_subscription_state', [
+        'Read the current Apple-side state of a subscription. Returns name, productId, and Apple\'s lifecycle state (MISSING_METADATA / READY_TO_SUBMIT / WAITING_FOR_REVIEW / IN_REVIEW / APPROVED / REJECTED / etc).',
+        '',
+        'Use this to verify a subscription is actually ready after capivv_create_product + capivv_set_subscription_review_screenshot. Apple\'s modern /v1/subscriptions and legacy /v1/inAppPurchases views can diverge — a subscription with all metadata + screenshot uploaded sometimes stays at MISSING_METADATA because the legacy mirror lags. Poll this every 30-60 seconds; if state doesn\'t progress within a few minutes, call capivv_touch_subscription or click Save in App Store Connect\'s web UI.',
+    ].join(' '), {
+        apple_subscription_id: z
+            .string()
+            .describe('Apple subscription ID (e.g. "6764778053") — the store-side ID, not the Capivv UUID.'),
+    }, async ({ apple_subscription_id }) => {
+        const info = await client.getSubscriptionState(apple_subscription_id);
+        return { content: [{ type: 'text', text: JSON.stringify(info, null, 2) }] };
+    });
+}

package/dist/tools/index.js

@@ -72,6 +72,9 @@ import { registerListIntegrationsTool } from './list-integrations.js';
 import { registerConnectAppleIntegrationTool } from './connect-apple-integration.js';
 import { registerConnectGoogleIntegrationTool } from './connect-google-integration.js';
 import { registerDisconnectIntegrationTool } from './disconnect-integration.js';
+import { registerSetSubscriptionReviewScreenshotTool } from './set-subscription-review-screenshot.js';
+import { registerGetSubscriptionStateTool } from './get-subscription-state.js';
+import { registerTouchSubscriptionTool } from './touch-subscription.js';
 export function registerAllTools(server, client) {
     // Identity — call this first to verify which workspace you're connected to
     registerWhoamiTool(server, client);
@@ -173,4 +176,13 @@ export function registerAllTools(server, client) {
     registerConnectAppleIntegrationTool(server, client);
     registerConnectGoogleIntegrationTool(server, client);
     registerDisconnectIntegrationTool(server, client);
+    // Subscription review screenshot (v0.5.5 — Apple's 3-step S3 upload flow
+    // wrapped in a single MCP call so the agent can take a subscription from
+    // MISSING_METADATA to READY_FOR_REVIEW in one step.)
+    registerSetSubscriptionReviewScreenshotTool(server, client);
+    // Subscription state probe + touch (v0.5.6 — workaround for Apple's
+    // modern-vs-legacy view divergence keeping subscriptions in
+    // MISSING_METADATA after a successful create.)
+    registerGetSubscriptionStateTool(server, client);
+    registerTouchSubscriptionTool(server, client);
 }

package/dist/tools/set-subscription-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 registerSetSubscriptionReviewScreenshotTool(server: McpServer, client: CapivvClient): void;

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

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+export function registerSetSubscriptionReviewScreenshotTool(server, client) {
+    server.tool('capivv_set_subscription_review_screenshot', [
+        '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.',
+        '',
+        'Get `apple_subscription_id` from the `store_create` block of capivv_create_product, from capivv_check_drift, or from App Store Connect.',
+    ].join(' '), {
+        apple_subscription_id: z
+            .string()
+            .describe('Apple subscription ID (e.g. "6764778053") — NOT the Capivv product UUID.'),
+        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 non-HTTPS sources. Mutually exclusive with image_url.'),
+        file_name: z
+            .string()
+            .optional()
+            .describe('Filename Apple stores on the screenshot resource. 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.setSubscriptionReviewScreenshot(args);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/tools/touch-subscription.d.ts

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

package/dist/tools/touch-subscription.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export function registerTouchSubscriptionTool(server, client) {
+    server.tool('capivv_touch_subscription', [
+        'BEST-EFFORT workaround for Apple\'s modern-vs-legacy view divergence.',
+        '',
+        'After capivv_create_product creates the subscription via Apple\'s /v1/subscriptions endpoint, a legacy /v1/inAppPurchases mirror is also created with its own state machine. The legacy record can stay at WAITING_FOR_SCREENSHOT (which keeps the modern view at MISSING_METADATA) even after the screenshot uploads cleanly, because Apple\'s state recompute pipeline still reads from the legacy view and the modern API doesn\'t reliably trigger that recompute.',
+        '',
+        'This tool does a no-op PATCH on the subscription (re-set name to its current value), which mirrors what clicking "Save" in App Store Connect\'s web UI appears to trigger. Whether it actually fires the recompute hasn\'t been confirmed in every state — call capivv_get_subscription_state 30-60 seconds afterwards to check. If state still doesn\'t progress, fall back to manual ASC web UI Save.',
+    ].join(' '), {
+        apple_subscription_id: z
+            .string()
+            .describe('Apple subscription ID (e.g. "6764778053") — the store-side ID, not the Capivv UUID.'),
+    }, async ({ apple_subscription_id }) => {
+        const result = await client.touchSubscription(apple_subscription_id);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/types.d.ts

@@ -68,6 +68,15 @@ export interface StoreCreateSummary {
         actual_cents: number;
         price_point_id?: string;
     }>;
+    /** Fields the orchestrator shortened to fit Apple's per-field length cap.
+     *  Empty / undefined when nothing was clipped. */
+    truncations?: Array<{
+        field: string;
+        original_chars: number;
+        truncated_chars: number;
+        limit: number;
+        locale: string;
+    }>;
 }
 export interface Entitlement {
     id: string;
@@ -554,3 +563,28 @@ export interface ConnectGoogleIntegrationResult {
         error: string;
     }>;
 }
+export interface SetSubscriptionReviewScreenshotRequest {
+    apple_subscription_id: string;
+    /** Public HTTPS URL the backend fetches. Either this or image_base64 is required. */
+    image_url?: string;
+    /** Base64-encoded raw image bytes. Either this or image_url is required. */
+    image_base64?: string;
+    /** Filename Apple records (defaults to screenshot.png). */
+    file_name?: string;
+}
+export interface SetSubscriptionReviewScreenshotResult {
+    apple_subscription_id: string;
+    screenshot_id: string;
+    bytes_uploaded: number;
+}
+export interface SubscriptionStateInfo {
+    apple_subscription_id: string;
+    product_id: string;
+    name: string | null;
+    state: string | null;
+}
+export interface TouchSubscriptionResult {
+    apple_subscription_id: string;
+    touched: boolean;
+    next_action: string;
+}

package/package.json

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