cfw-autumn/shared/api/common/jsDocs.ts

import {
	createJSDocDescription,
	docLink,
	example,
} from "@api/utils/openApiHelpers";
// import { TrackParamsSchema } from "../balances/trackModels";
import { SetUsageParamsSchema } from "../balances/usageModels";
// import { CheckParamsSchema } from "../core/checkModels";
import {
	BillingPortalParamsSchema,
	CancelBodySchema,
	QueryParamsSchema,
} from "../core/coreOpModels";
import { SetupPaymentParamsV1Schema } from "../billing/setupPayment/setupPaymentParamsV1";
import { ExtAttachBodyV0Schema, ExtCheckoutParamsV0Schema } from "../models";
/**
 * Centralized JSDoc declarations for all core API methods.
 * These are used by the OpenAPI spec generator and propagate to SDK documentation.
 */

export const attachJsDoc = createJSDocDescription({
	description:
		"Enables a product for a customer and processes payment if their payment method is already on file.",
	whenToUse:
		"Use this when the customer already has a payment method saved. For new customers without payment info, use `checkout` instead.",
	body: ExtAttachBodyV0Schema,
	examples: [
		example({
			values: {
				customer_id: "cus_123",
				product_id: "pro_plan",
			},
			description: "Attach a product to a customer",
		}),
	],
	methodName: "attach",
	docs: [
		docLink({
			url: "https://docs.useautumn.com/api-reference/core/attach",
			title: "Product Attachments",
		}),
	],
});

export const checkoutJsDoc = createJSDocDescription({
	description:
		"Creates a checkout session for a customer to purchase a product with payment collection.",
	whenToUse:
		"Use this for new customers or when payment info is needed. For customers with existing payment methods, use `attach` instead.",
	body: ExtCheckoutParamsV0Schema,
	examples: [
		example({
			values: {
				customer_id: "cus_123",
				product_id: "pro_plan",
			},
			description: "Create a checkout session",
		}),
	],
	methodName: "checkout",
	docs: [
		docLink({
			url: "https://docs.useautumn.com/api-reference/core/checkout",
			title: "Checkout Sessions",
		}),
	],
});

// export const checkJsDoc = createJSDocDescription({
// 	description:
// 		"Check whether a customer has access to a product, feature or remaining usage.",
// 	body: CheckParamsSchema,
// 	examples: [
// 		example({
// 			values: {
// 				customer_id: "cus_123",
// 				feature_id: "api_calls",
// 			},
// 			description: "Check feature access",
// 		}),
// 	],
// 	methodName: "check",
// });

// export const trackJsDoc = createJSDocDescription({
// 	description:
// 		"Track usage events for metered features or record analytics events.",
// 	whenToUse:
// 		"Use this to increment usage counters for pay-as-you-go features or track customer activity.",
// 	body: TrackParamsSchema,
// 	examples: [
// 		example({
// 			values: {
// 				customer_id: "cus_123",
// 				feature_id: "api_calls",
// 				value: 1,
// 			},
// 			description: "Track a usage event",
// 		}),
// 	],
// 	methodName: "track",
// 	docs: [
// 		docLink({
// 			url: "https://docs.useautumn.com/api-reference/core/track",
// 			title: "Usage Tracking",
// 		}),
// 	],
// });

export const cancelJsDoc = createJSDocDescription({
	description: "Cancel a customer's subscription to a product.",
	whenToUse:
		"Use this when a customer wants to stop their subscription. Supports immediate or end-of-period cancellation.",
	body: CancelBodySchema,
	examples: [
		example({
			values: {
				customer_id: "cus_123",
				product_id: "pro_plan",
			},
			description: "Cancel a subscription",
		}),
	],
	methodName: "cancel",
	docs: [
		docLink({
			url: "https://docs.useautumn.com/api-reference/core/cancel",
			title: "Cancel Subscriptions",
		}),
	],
});

export const setupPaymentJsDoc = createJSDocDescription({
	description:
		"Creates a session for a customer to add or update their payment method.",
	whenToUse:
		"Use this to collect payment information without immediately charging the customer.",
	body: SetupPaymentParamsV1Schema.meta({
		id: "SetupPaymentParams",
		description: "Parameters for setting up a payment method",
	}),
	examples: [
		example({
			values: {
				customer_id: "cus_123",
				success_url: "https://example.com/success",
			},
			description: "Setup payment method",
		}),
	],
	methodName: "setupPayment",
	docs: [
		docLink({
			url: "https://docs.useautumn.com/api-reference/core/setup-payment",
			title: "Payment Setup",
		}),
	],
});

export const billingPortalJsDoc = createJSDocDescription({
	description:
		"Creates a billing portal session where customers can manage their subscription and payment methods.",
	whenToUse:
		"Use this to give customers self-service access to view invoices, update payment info, and manage subscriptions.",
	body: BillingPortalParamsSchema,
	examples: [
		example({
			values: {
				customer_id: "cus_123",
				return_url: "https://example.com/account",
			},
			description: "Open billing portal",
		}),
	],
	methodName: "billingPortal",
	docs: [
		docLink({
			url: "https://docs.useautumn.com/api-reference/core/billing-portal",
			title: "Billing Portal",
		}),
	],
});

export const queryJsDoc = createJSDocDescription({
	description:
		"Query usage analytics for a customer's features over a specified time range.",
	whenToUse:
		"Use this to retrieve historical usage data for dashboards, reports, or usage displays.",
	body: QueryParamsSchema.meta({
		id: "QueryParams",
		description: "Parameters for querying analytics data",
	}),
	examples: [
		example({
			values: {
				customer_id: "cus_123",
				feature_id: "api_calls",
				range: "7d",
			},
			description: "Query 7-day usage",
		}),
	],
	methodName: "query",
	docs: [
		docLink({
			url: "https://docs.useautumn.com/api-reference/core/query",
			title: "Analytics Queries",
		}),
	],
});

export const setUsageJsDoc = createJSDocDescription({
	description:
		"Set usage for a feature. This is similar to /track instead of incrementing usage, it sets the usage value to exactly what is provided.",
	whenToUse: "Use this to set usage for a feature instead of incrementing it.",
	body: SetUsageParamsSchema,
	examples: [
		example({
			values: {
				customer_id: "123",
				feature_id: "api_calls",
				value: 10000,
			},
			description: "Set usage for a feature",
		}),
	],
	methodName: "usage",
	docs: [
		docLink({
			url: "https://docs.useautumn.com/api-reference/core/usage",
			title: "Set Usage",
		}),
	],
});