admanagekit-mcp-server 1.0.0

package/content/wiki/Subscriptions.md

@@ -0,0 +1,368 @@
+# Subscriptions
+
+AdManageKit provides comprehensive subscription management including state tracking, upgrade/downgrade support, and lifecycle management.
+
+## Setting Up Subscriptions
+
+### Define Subscription Products
+
+```kotlin
+val products = listOf(
+    // Subscription with free trial offer
+    PurchaseItem("premium_monthly", "free_trial_7d", TYPE_IAP.SUBSCRIPTION),
+
+    // Subscription without trial
+    PurchaseItem("premium_yearly", null, TYPE_IAP.SUBSCRIPTION),
+
+    // Multiple tiers
+    PurchaseItem("basic_monthly", null, TYPE_IAP.SUBSCRIPTION),
+    PurchaseItem("pro_monthly", "intro_offer", TYPE_IAP.SUBSCRIPTION)
+)
+```
+
+### Initialize
+
+```kotlin
+AppPurchase.getInstance().initBilling(application, products)
+```
+
+## Subscribing
+
+```kotlin
+// Start subscription flow
+AppPurchase.getInstance().subscribe(activity, "premium_monthly")
+```
+
+## Subscription States
+
+### State Enum
+
+```kotlin
+enum class SubscriptionState {
+    ACTIVE,          // Subscribed and will renew
+    CANCELLED,       // Cancelled but still has access
+    GRACE_PERIOD,    // Payment issue, still has access (server-side only)
+    ON_HOLD,         // Payment issue, no access (server-side only)
+    PAUSED,          // User paused (server-side only)
+    EXPIRED,         // Subscription ended
+    NOT_SUBSCRIPTION // Product is not a subscription
+}
+```
+
+### Client-Side Detection
+
+| State | Detectable Client-Side | How |
+|-------|----------------------|-----|
+| ACTIVE | Yes | `isAutoRenewing = true` |
+| CANCELLED | Yes | `isAutoRenewing = false`, still in purchase list |
+| GRACE_PERIOD | No | Requires server API |
+| ON_HOLD | No | Requires server API |
+| PAUSED | No | Requires server API |
+| EXPIRED | Yes | Not returned by `queryPurchasesAsync` |
+
+## Checking Subscription Status
+
+### Basic Checks
+
+```kotlin
+// Any subscription active?
+if (AppPurchase.getInstance().isSubscribed()) {
+    showPremiumContent()
+}
+
+// Specific subscription active?
+if (AppPurchase.getInstance().isSubscribed("premium_yearly")) {
+    showYearlyBenefits()
+}
+```
+
+### Get Subscription State
+
+```kotlin
+val state = AppPurchase.getInstance().getSubscriptionState("premium_monthly")
+
+when (state) {
+    SubscriptionState.ACTIVE -> {
+        // User is subscribed and will renew
+        showPremiumUI()
+    }
+    SubscriptionState.CANCELLED -> {
+        // User cancelled but still has access until expiration
+        showRenewalPrompt()
+    }
+    SubscriptionState.EXPIRED -> {
+        // Subscription ended
+        showSubscribeButton()
+    }
+    else -> {
+        // Not subscribed or other state
+    }
+}
+```
+
+### Additional Checks
+
+```kotlin
+// Check if any subscription is cancelled (but still active)
+if (AppPurchase.getInstance().hasSubscriptionCancelled()) {
+    showResubscribePrompt()
+}
+
+// Check if all subscriptions will renew
+if (AppPurchase.getInstance().willSubscriptionsRenew()) {
+    // User is committed subscriber
+}
+
+// Get all active subscriptions
+val subscriptions = AppPurchase.getInstance().getActiveSubscriptions()
+for (sub in subscriptions) {
+    println("${sub.getFirstProductId()}: ${sub.getSubscriptionStateString()}")
+}
+```
+
+## Subscription Details
+
+### Get Subscription PurchaseResult
+
+```kotlin
+val subscription = AppPurchase.getInstance().getSubscription("premium_monthly")
+if (subscription != null) {
+    // Basic info
+    val orderId = subscription.orderId
+    val purchaseTime = subscription.getPurchaseTimeFormatted()
+
+    // State info
+    val isActive = subscription.isSubscriptionActive()
+    val willRenew = subscription.willSubscriptionRenew()
+    val isCancelled = subscription.isSubscriptionCancelled()
+    val stateString = subscription.getSubscriptionStateString()
+
+    // Display
+    showSubscriptionInfo(
+        status = stateString,      // "Active", "Cancelled (access until expiration)"
+        since = purchaseTime,      // "2024-01-15 14:30:00"
+        willRenew = willRenew      // true/false
+    )
+}
+```
+
+## Subscription Pricing
+
+```kotlin
+// Get formatted price
+val monthlyPrice = AppPurchase.getInstance().getPriceSub("premium_monthly")
+// "$9.99"
+
+val yearlyPrice = AppPurchase.getInstance().getPriceSub("premium_yearly")
+// "$99.99"
+```
+
+## Trial Offers
+
+Specify trial offer ID when creating PurchaseItem:
+
+```kotlin
+// The second parameter is the offer ID from Google Play Console
+PurchaseItem("premium_monthly", "free_trial_7d", TYPE_IAP.SUBSCRIPTION)
+```
+
+The library automatically selects the matching offer when subscribing.
+
+## Handling Subscription Changes
+
+See [[Subscription Upgrades]] for upgrade/downgrade handling.
+
+## Best Practices
+
+### 1. Always Show Subscription State
+
+```kotlin
+fun updateSubscriptionUI() {
+    val state = AppPurchase.getInstance().getSubscriptionState("premium_monthly")
+
+    subscriptionBadge.text = when (state) {
+        SubscriptionState.ACTIVE -> "Premium Member"
+        SubscriptionState.CANCELLED -> "Premium (Expires Soon)"
+        else -> "Free User"
+    }
+}
+```
+
+### 2. Prompt Cancelled Users to Resubscribe
+
+```kotlin
+if (AppPurchase.getInstance().hasSubscriptionCancelled()) {
+    showDialog(
+        title = "Your subscription is ending",
+        message = "Renew now to keep premium features",
+        action = "Renew" to { reopenSubscription() }
+    )
+}
+
+fun reopenSubscription() {
+    // This will show the resubscribe flow in Google Play
+    AppPurchase.getInstance().subscribe(activity, "premium_monthly")
+}
+```
+
+### 3. Restore Purchases on App Start
+
+```kotlin
+override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+
+    // Verify purchases to restore subscription state
+    AppPurchase.getInstance().verifyPurchased(true)
+}
+```
+
+### 4. Handle Grace Period (Server-Side)
+
+For grace period detection, implement server-side verification using Google Play Developer API and Real-time Developer Notifications (RTDN).
+
+## Subscription Expiry Verification
+
+The Google Play Billing Library does NOT provide subscription expiry dates client-side. To get accurate expiry dates, you need server-side verification.
+
+### Setting Up Verification Callback
+
+```kotlin
+// In Application.onCreate() or early initialization
+AppPurchase.getInstance().setSubscriptionVerificationCallback { packageName, subscriptionId, purchaseToken, listener ->
+    // Call your backend API
+    yourBackendApi.verifySubscription(packageName, subscriptionId, purchaseToken,
+        onSuccess = { expiryTimeMillis, isAutoRenewing ->
+            val details = SubscriptionVerificationCallback.SubscriptionDetails.Builder()
+                .setExpiryTimeMillis(expiryTimeMillis)
+                .setAutoRenewing(isAutoRenewing)
+                .build()
+            listener.onVerified(details)
+        },
+        onError = { error ->
+            listener.onVerificationFailed(error)
+        }
+    )
+}
+```
+
+### Verifying a Subscription
+
+```kotlin
+AppPurchase.getInstance().verifySubscription("premium_monthly",
+    object : AppPurchase.SubscriptionVerificationListener {
+        override fun onVerified(subscription: PurchaseResult) {
+            // Expiry info now available
+            val expiryDate = subscription.getExpiryTimeFormatted("dd MMM yyyy")
+            val remainingDays = subscription.getRemainingDays()
+            val isExpired = subscription.isExpired()
+
+            updateUI(expiryDate, remainingDays)
+        }
+
+        override fun onVerificationFailed(errorMessage: String?) {
+            Log.e("Subscription", "Verification failed: $errorMessage")
+        }
+    }
+)
+
+// Verify all active subscriptions at once
+AppPurchase.getInstance().verifyAllSubscriptions(listener)
+```
+
+### Getting Expiry Information
+
+After verification, expiry data is stored and accessible:
+
+```kotlin
+// Get expiry time in milliseconds
+val expiryMillis = AppPurchase.getInstance().getSubscriptionExpiryTime("premium_monthly")
+
+// Get formatted expiry date
+val expiryDate = AppPurchase.getInstance().getSubscriptionExpiryTimeFormatted("premium_monthly")
+// "2024-03-15 14:30:00"
+
+// Custom format
+val customFormat = AppPurchase.getInstance().getSubscriptionExpiryTimeFormatted("premium_monthly", "dd MMM yyyy")
+// "15 Mar 2024"
+
+// Get remaining days
+val daysLeft = AppPurchase.getInstance().getSubscriptionRemainingDays("premium_monthly")
+// 30
+
+// Check if expired
+val isExpired = AppPurchase.getInstance().isSubscriptionExpired("premium_monthly")
+// false
+```
+
+### Using PurchaseResult Directly
+
+```kotlin
+val subscription = AppPurchase.getInstance().getSubscription("premium_monthly")
+if (subscription != null && subscription.isExpiryVerified()) {
+    // Expiry data available
+    val expiryDate = subscription.getExpiryDate()           // Date object
+    val expiryFormatted = subscription.getExpiryTimeFormatted()  // String
+    val remainingDays = subscription.getRemainingDays()     // Int (-1 if not verified)
+    val remainingMillis = subscription.getRemainingTime()   // Long (-1 if not verified)
+    val isExpired = subscription.isExpired()               // Boolean
+}
+```
+
+### Backend API Implementation
+
+Your backend should call Google Play Developer API:
+
+```
+GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/subscriptionsv2/tokens/{purchaseToken}
+```
+
+Response includes:
+- `expiryTime` - RFC 3339 timestamp
+- `subscriptionState` - ACTIVE, CANCELED, IN_GRACE_PERIOD, ON_HOLD, PAUSED, EXPIRED
+- `linkedPurchaseToken` - For upgrade/downgrade tracking
+
+### Example: Show Subscription Status UI
+
+```kotlin
+fun updateSubscriptionUI() {
+    val subscription = AppPurchase.getInstance().getSubscription("premium_monthly")
+
+    if (subscription == null) {
+        showNotSubscribedUI()
+        return
+    }
+
+    if (!subscription.isExpiryVerified()) {
+        // Verify first
+        AppPurchase.getInstance().verifySubscription("premium_monthly",
+            object : AppPurchase.SubscriptionVerificationListener {
+                override fun onVerified(sub: PurchaseResult) {
+                    showSubscriptionDetails(sub)
+                }
+                override fun onVerificationFailed(error: String?) {
+                    showBasicSubscriptionUI(subscription)
+                }
+            }
+        )
+    } else {
+        showSubscriptionDetails(subscription)
+    }
+}
+
+fun showSubscriptionDetails(subscription: PurchaseResult) {
+    val daysLeft = subscription.getRemainingDays()
+
+    when {
+        subscription.isExpired() -> {
+            statusText.text = "Subscription Expired"
+            renewButton.visibility = View.VISIBLE
+        }
+        daysLeft <= 7 && !subscription.isAutoRenewing -> {
+            statusText.text = "Expires in $daysLeft days"
+            renewPrompt.visibility = View.VISIBLE
+        }
+        else -> {
+            statusText.text = "Premium until ${subscription.getExpiryTimeFormatted("dd MMM yyyy")}"
+        }
+    }
+}

package/content/wiki/_Footer.md

@@ -0,0 +1,3 @@
+---
+
+**AdManageKit** v3.3.4 | [GitHub](https://github.com/i2hammad/AdManageKit) | [API Docs](https://i2hammad.github.io/AdManageKit/) | [Report Issue](https://github.com/i2hammad/AdManageKit/issues) | [Buy me a coffee](https://buymeacoffee.com/i2hammad)

package/content/wiki/_Sidebar.md

@@ -0,0 +1,18 @@
+### Ad Types
+- [[Interstitial Ads]]
+- [[Rewarded Ads]]
+- [[App Open Ads]]
+- [[Native Ads|NativeAdManager]]
+- [[Banner Ads]]
+
+### Features
+- [[Ad Loading Strategies]]
+- [[Configuration]]
+- [[Jetpack Compose]]
+
+### Billing
+- [[Billing Integration]]
+- [[Purchase Categories]]
+- [[Consumable Products]]
+- [[Subscriptions]]
+- [[Subscription Upgrades]]

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const server_js_1 = require("./server.js");
+(0, server_js_1.startServer)();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AACA,2CAA0C;AAE1C,IAAA,uBAAW,GAAE,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1 @@
+export declare function startServer(): Promise<void>;

package/dist/server.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startServer = startServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const documentation_js_1 = require("./tools/documentation.js");
+const code_generation_js_1 = require("./tools/code-generation.js");
+async function startServer() {
+    const server = new mcp_js_1.McpServer({
+        name: "admanagekit-docs",
+        version: "1.0.0",
+    });
+    (0, documentation_js_1.registerDocumentationTools)(server);
+    (0, code_generation_js_1.registerCodeGenerationTools)(server);
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";;AAKA,kCAWC;AAhBD,oEAAoE;AACpE,wEAAiF;AACjF,+DAAsE;AACtE,mEAAyE;AAElE,KAAK,UAAU,WAAW;IAC/B,MAAM,MAAM,GAAG,IAAI,kBAAS,CAAC;QAC3B,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,IAAA,6CAA0B,EAAC,MAAM,CAAC,CAAC;IACnC,IAAA,gDAA2B,EAAC,MAAM,CAAC,CAAC;IAEpC,MAAM,SAAS,GAAG,IAAI,+BAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}

package/dist/tools/code-generation.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerCodeGenerationTools(server: McpServer): void;

package/dist/tools/code-generation.js

@@ -0,0 +1,264 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCodeGenerationTools = registerCodeGenerationTools;
+const zod_1 = require("zod");
+const templates_js_1 = require("../utils/templates.js");
+function registerCodeGenerationTools(server) {
+    // Tool 7: generate_config
+    server.tool("generate_config", "Generate AdManageKitConfig setup code for your Application class. Produces complete configuration including ad initialization, billing setup, and loading strategies.", {
+        language: zod_1.z
+            .enum(["kotlin", "java"])
+            .optional()
+            .default("kotlin")
+            .describe("Output language (default: kotlin)"),
+        features: zod_1.z
+            .object({
+            debug_mode: zod_1.z.boolean().optional().describe("Enable debug mode"),
+            smart_preloading: zod_1.z
+                .boolean()
+                .optional()
+                .describe("Enable smart ad preloading"),
+            auto_retry: zod_1.z
+                .boolean()
+                .optional()
+                .describe("Enable automatic retry on failed ad loads"),
+            max_retry_attempts: zod_1.z
+                .number()
+                .optional()
+                .describe("Max retry attempts (default: 3)"),
+            performance_metrics: zod_1.z
+                .boolean()
+                .optional()
+                .describe("Enable performance tracking"),
+            interstitial_strategy: zod_1.z
+                .enum(["ON_DEMAND", "ONLY_CACHE", "HYBRID"])
+                .optional(),
+            app_open_strategy: zod_1.z
+                .enum(["ON_DEMAND", "ONLY_CACHE", "HYBRID"])
+                .optional(),
+            native_strategy: zod_1.z.enum(["ON_DEMAND", "HYBRID"]).optional(),
+            interstitial_auto_reload: zod_1.z.boolean().optional(),
+            app_open_auto_reload: zod_1.z.boolean().optional(),
+            rewarded_auto_reload: zod_1.z.boolean().optional(),
+            billing: zod_1.z
+                .boolean()
+                .optional()
+                .describe("Include billing setup"),
+            app_open_ad_unit: zod_1.z
+                .string()
+                .optional()
+                .describe("App open ad unit ID"),
+            test_mode: zod_1.z.boolean().optional().describe("Enable test mode"),
+        })
+            .optional()
+            .default({}),
+    }, async ({ language, features }) => {
+        const code = (0, templates_js_1.generateConfig)({
+            language,
+            ...features,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `\`\`\`${language}\n${code}\n\`\`\``,
+                },
+            ],
+        };
+    });
+    // Tool 8: generate_ad_integration
+    server.tool("generate_ad_integration", "Generate complete ad integration code for a specific ad type. Includes XML layout, loading code, display code, and callback handling.", {
+        ad_type: zod_1.z
+            .enum([
+            "interstitial",
+            "banner",
+            "native_small",
+            "native_medium",
+            "native_large",
+            "native_template",
+            "app_open",
+            "rewarded",
+        ])
+            .describe("The type of ad to generate code for"),
+        language: zod_1.z
+            .enum(["kotlin", "java"])
+            .optional()
+            .default("kotlin")
+            .describe("Output language (default: kotlin)"),
+        ad_unit_id: zod_1.z
+            .string()
+            .optional()
+            .describe("AdMob ad unit ID (default: test ad unit)"),
+        options: zod_1.z
+            .object({
+            display_mode: zod_1.z
+                .enum([
+                "force",
+                "time_based",
+                "count_based",
+                "builder",
+                "splash_wait",
+            ])
+                .optional()
+                .describe("For interstitial: how to show the ad"),
+            loading_strategy: zod_1.z
+                .enum(["ON_DEMAND", "ONLY_CACHE", "HYBRID"])
+                .optional()
+                .describe("Loading strategy to use"),
+            use_caching: zod_1.z
+                .boolean()
+                .optional()
+                .describe("For native ads: use cached ads"),
+            template: zod_1.z
+                .string()
+                .optional()
+                .describe("For native_template: template name (e.g., MATERIAL3, CARD_MODERN)"),
+            collapsible: zod_1.z
+                .boolean()
+                .optional()
+                .describe("For banner: use collapsible banner"),
+            with_callbacks: zod_1.z
+                .boolean()
+                .optional()
+                .describe("Include full callback handling (default: true)"),
+            with_fallbacks: zod_1.z
+                .boolean()
+                .optional()
+                .describe("For interstitial builder: include fallback ad units"),
+            frequency_control: zod_1.z
+                .object({
+                every_nth_time: zod_1.z.number().optional(),
+                max_shows: zod_1.z.number().optional(),
+                min_interval_seconds: zod_1.z.number().optional(),
+            })
+                .optional(),
+            exclude_activities: zod_1.z
+                .array(zod_1.z.string())
+                .optional()
+                .describe("For app_open: activity classes to exclude"),
+            auto_reload: zod_1.z
+                .boolean()
+                .optional()
+                .describe("Auto-reload after dismissal"),
+        })
+            .optional()
+            .default({}),
+    }, async ({ ad_type, language, ad_unit_id, options }) => {
+        const code = (0, templates_js_1.generateAdIntegration)({
+            ad_type,
+            language,
+            ad_unit_id,
+            ...options,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `\`\`\`${language}\n${code}\n\`\`\``,
+                },
+            ],
+        };
+    });
+    // Tool 9: generate_billing_code
+    server.tool("generate_billing_code", "Generate billing/purchase integration code for AdManageKit. Supports in-app purchases, subscriptions, consumable products, and subscription management.", {
+        language: zod_1.z
+            .enum(["kotlin", "java"])
+            .optional()
+            .default("kotlin")
+            .describe("Output language (default: kotlin)"),
+        scenario: zod_1.z
+            .enum([
+            "setup",
+            "purchase",
+            "subscribe",
+            "consumable",
+            "subscription_management",
+            "expiry_verification",
+            "complete",
+        ])
+            .describe("Which billing scenario to generate code for"),
+        products: zod_1.z
+            .array(zod_1.z.object({
+            product_id: zod_1.z.string(),
+            type: zod_1.z.enum(["PURCHASE", "SUBSCRIPTION"]),
+            category: zod_1.z
+                .enum([
+                "CONSUMABLE",
+                "FEATURE_UNLOCK",
+                "LIFETIME_PREMIUM",
+                "REMOVE_ADS",
+            ])
+                .optional(),
+            offer_token: zod_1.z.string().optional(),
+        }))
+            .optional()
+            .describe("Product definitions to include"),
+    }, async ({ language, scenario, products }) => {
+        const code = (0, templates_js_1.generateBillingCode)({
+            language,
+            scenario,
+            products,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `\`\`\`${language}\n${code}\n\`\`\``,
+                },
+            ],
+        };
+    });
+    // Tool 10: generate_compose_code
+    server.tool("generate_compose_code", "Generate Jetpack Compose ad integration code. Supports all Compose ad components: BannerAdCompose, NativeTemplateCompose, rememberInterstitialAd, ConditionalAd, CacheWarmingEffect.", {
+        component: zod_1.z
+            .enum([
+            "banner",
+            "native_template",
+            "native_small",
+            "native_medium",
+            "native_large",
+            "interstitial",
+            "interstitial_state",
+            "conditional_ad",
+            "cache_warming",
+            "complete_screen",
+        ])
+            .describe("Which Compose component to generate"),
+        ad_unit_id: zod_1.z
+            .string()
+            .optional()
+            .describe("AdMob ad unit ID (default: test unit)"),
+        options: zod_1.z
+            .object({
+            template: zod_1.z
+                .string()
+                .optional()
+                .describe("For native_template: NativeAdTemplate value (e.g., MATERIAL3)"),
+            loading_strategy: zod_1.z
+                .enum(["ON_DEMAND", "ONLY_CACHE", "HYBRID"])
+                .optional(),
+            with_callbacks: zod_1.z.boolean().optional(),
+            show_mode: zod_1.z
+                .enum(["TIME", "COUNT", "FORCE", "FORCE_WITH_DIALOG"])
+                .optional()
+                .describe("For interstitial_state: how to show the ad"),
+        })
+            .optional()
+            .default({}),
+    }, async ({ component, ad_unit_id, options }) => {
+        const code = (0, templates_js_1.generateComposeCode)({
+            component,
+            ad_unit_id,
+            ...options,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `\`\`\`kotlin\n${code}\n\`\`\``,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=code-generation.js.map