### Full Autumn Configuration Example

Source: https://github.com/useautumn/autumn/blob/dev/apps/docs/mintlify/cli/config.mdx

A comprehensive configuration file demonstrating feature definitions, plan setups (free, pro, add-on), and various item configurations including included amounts, pricing, and free trials.

```typescript
import { feature, item, plan } from 'atmn';

// Features
export const messages = feature({
  id: 'messages',
  name: 'Messages',
  type: 'metered',
  consumable: true,
});

export const seats = feature({
  id: 'seats',
  name: 'Seats',
  type: 'metered',
  consumable: false,
});

export const sso = feature({
  id: 'sso',
  name: 'SSO',
  type: 'boolean',
});

// Plans
export const free = plan({
  id: 'free',
  name: 'Free',
  autoEnable: true,
  items: [
    item({
      featureId: messages.id,
      included: 5,
      reset: { interval: 'month' },
    }),
    item({
      featureId: seats.id,
      included: 1,
    }),
  ],
});

export const pro = plan({
  id: 'pro',
  name: 'Pro',
  price: { amount: 20, interval: 'month' },
  freeTrial: {
    durationLength: 14,
    durationType: 'day',
    cardRequired: true,
  },
  items: [
    item({
      featureId: messages.id,
      included: 1000,
      reset: { interval: 'month' },
    }),
    item({
      featureId: seats.id,
      included: 5,
      price: {
        amount: 10,
        interval: 'month',
        billingMethod: 'usage_based',
        billingUnits: 1,
      },
    }),
    item({
      featureId: sso.id,
    }),
  ],
});

export const topUp = plan({
  id: 'top_up',
  name: 'Message Top-Up',
  addOn: true,
  items: [
    item({
      featureId: messages.id,
      price: {
        amount: 5,
        billingUnits: 100,
        billingMethod: 'prepaid',
      },
    }),
  ],
});
```

--------------------------------

### Install @useautumn/gateway with bun

Source: https://github.com/useautumn/autumn/blob/dev/apps/docs/mintlify/documentation/external-providers/ai-sdk.mdx

Install the gateway package using bun.

```bash
bun add @useautumn/gateway
```

--------------------------------

### SDK Example Usage

Source: https://github.com/useautumn/autumn/blob/dev/packages/sdk/README.md

Example demonstrating how to initialize and use the Autumn SDK client.

```APIDOC
## SDK Example Usage

### Example

```typescript
import { Autumn } from "@useautumn/sdk";

const autumn = new Autumn({
  xApiVersion: "2.3.0",
  secretKey: process.env["AUTUMN_SECRET_KEY"] ?? "",
});

async function run() {
  const result = await autumn.check({
    customerId: "cus_123",
    featureId: "messages",
  });

  console.log(result);
}

run();

```
```

--------------------------------

### Setup Payment for Trial

Source: https://github.com/useautumn/autumn/blob/dev/apps/docs/mintlify/examples/trial-card-not-required.mdx

Initiates the payment setup process for a customer, allowing them to start a trial without an upfront card payment. If a payment method is on file, they will be charged; otherwise, the trial will expire.

```APIDOC
## POST /v1/billing.setup_payment

### Description
Initiates the payment setup process for a customer. If a payment method is on file, the customer will be charged. Otherwise, the trial plan will expire. If there's another non-trial auto-enable plan (like a free tier), it will be automatically enabled.

### Method
POST

### Endpoint
https://api.useautumn.com/v1/billing.setup_payment

### Parameters
#### Request Body
- **customer_id** (string) - Required - The ID of the customer.
- **success_url** (string) - Required - The URL to redirect the customer to after successful setup.
```

--------------------------------

### Install @useautumn/gateway

Source: https://github.com/useautumn/autumn/blob/dev/packages/gateway/README.md

Install the gateway package using npm or bun.

```bash
npm install @useautumn/gateway
# or
bun add @useautumn/gateway
```

--------------------------------

### Install @useautumn/gateway with yarn

Source: https://github.com/useautumn/autumn/blob/dev/apps/docs/mintlify/documentation/external-providers/ai-sdk.mdx

Install the gateway package using yarn.

```bash
yarn add @useautumn/gateway
```

--------------------------------

### Install SDK with Poetry

Source: https://github.com/useautumn/autumn/blob/dev/others/python-sdk/README.md

Install the SDK using the Poetry dependency management tool.

```bash
poetry add git+<UNSET>.git
```

--------------------------------

### Install SDK with uv

Source: https://github.com/useautumn/autumn/blob/dev/others/python-sdk/README.md

Install the SDK using the uv package manager. This is a fast alternative to pip.

```bash
uv add git+<UNSET>.git
```

--------------------------------

### Run Example Script

Source: https://github.com/useautumn/autumn/blob/dev/packages/sdk/examples/README.md

Build the project and execute an example TypeScript file using tsx.

```bash
npm run build && npx tsx example.ts
```

--------------------------------

### Install @useautumn/gateway with npm

Source: https://github.com/useautumn/autumn/blob/dev/apps/docs/mintlify/documentation/external-providers/ai-sdk.mdx

Install the gateway package using npm.

```bash
npm install @useautumn/gateway
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/useautumn/autumn/blob/dev/README.md

Install the project dependencies using bun. Ensure you have bun installed before running this command.

```bash
bun install
```

--------------------------------

### Install SDK with pip

Source: https://github.com/useautumn/autumn/blob/dev/others/python-sdk/README.md

Install the SDK using the standard pip package manager.

```bash
pip install git+<UNSET>.git
```

--------------------------------

### Install @useautumn/gateway with pnpm

Source: https://github.com/useautumn/autumn/blob/dev/apps/docs/mintlify/documentation/external-providers/ai-sdk.mdx

Install the gateway package using pnpm.

```bash
pnpm add @useautumn/gateway
```

--------------------------------

### SDK Installation

Source: https://github.com/useautumn/autumn/blob/dev/packages/sdk/README.md

Instructions for installing the Autumn SDK using various package managers.

```APIDOC
## SDK Installation

To finish publishing your SDK to npm and others you must [run your first generation action](https://www.speakeasy.com/docs/github-setup#step-by-step-guide).

The SDK can be installed with either [npm](https://www.npmjs.com/), [pnpm](https://pnpm.io/), [bun](https://bun.sh/) or [yarn](https://classic.yarnpkg.com/en/) package managers.

### NPM

```bash
npm add <UNSET>
```

### PNPM

```bash
pnpm add <UNSET>
```

### Bun

```bash
bun add <UNSET>
```

### Yarn

```bash
yarn add <UNSET>
```

> [!NOTE]
> This package is published with CommonJS and ES Modules (ESM) support.
```

--------------------------------

### Install SDK with Bun

Source: https://github.com/useautumn/autumn/blob/dev/packages/sdk/README.md

Use this command to install the Autumn SDK using the Bun package manager.

```bash
bun add <UNSET>
```

--------------------------------

### Simplest AI Credit System Setup

Source: https://github.com/useautumn/autumn/blob/dev/apps/docs/mintlify/documentation/modelling-pricing/credit-systems.mdx

This example shows the most basic setup for an AI credit system with a single default markup applied to all models.

```typescript
import { feature } from 'atmn';

export const aiCredits = feature({
  id: 'ai_credits',
  name: 'AI Credits',
  type: 'ai_credit_system',
  defaultMarkup: 30, // every model billed at models.dev cost + 30%
});
```

--------------------------------

### Run Load Test Setup and Execution

Source: https://github.com/useautumn/autumn/blob/dev/server/perf/load-test/README.md

Execute the one-time setup script to create products and customers, then run the general load test or the memory leak detection test.

```bash
cd server

# 1. One-time setup (creates products + 500 customers with Stripe PMs)
bun loadtest:setup

# 2. Run load test
bun loadtest:leak    # memory leak detection (11 min, ~30 req/s)
bun loadtest         # general load test (4 min, up to ~75 req/s)
```

--------------------------------

### Get RevenueCat Keys Response Example

Source: https://github.com/useautumn/autumn/blob/dev/apps/docs/mintlify/api-reference/platform/getRevenueCatKeys.mdx

This example demonstrates the structure of a successful response when retrieving RevenueCat API keys. It includes application details, API keys, and an OAuth access token.

```json
{
  "apps": [
    {
      "app_id": "app1a2b3c4d",
      "app_type": "test_store",
      "name": "Acme (Test Store)",
      "api_keys": [
        {
          "id": "apikey12345",
          "key": "test_aBcDeFgHiJkLmNoPqRsTuVwXyZ",
          "environment": "production",
          "app_id": "app1a2b3c4"
        }
      ]
    }
  ],
  "oauth_access_token": "atk_aBcDeFgHiJkLmNoPqRsTuVwXyZ"
}
```

--------------------------------

### Start Development Agent Services

Source: https://github.com/useautumn/autumn/blob/dev/scripts/setup/AGENT_README.md

Starts all local services, sets up the database, and launches development servers. Run this command every session.

```bash
bun dev:agent
```

--------------------------------

### Enable Pay-as-you-go with Payment Setup

Source: https://github.com/useautumn/autumn/blob/dev/apps/docs/mintlify/examples/pay-as-you-go-overages.mdx

Use this to prompt users to switch to pay-as-you-go and collect their payment details without immediate charge. This is useful when users approach or exceed their plan limits.

```jsx
import { useCustomer } from "autumn-js/react";

export default function EnableOveragesButton() {
  const { attach } = useCustomer();

  return (
    <button
      onClick={async () => {
        const { data } = await attach({
          productId: "pay_as_you_go",
          setupPayment: true,
        });

        if (data?.url) {
          window.location.href = data.url;
        }
      }}
    >
      Enable Pay-as-you-go
    </button>
  );
}
```

```typescript
import { Autumn } from "autumn-js";

const autumn = new Autumn({
  secretKey: 'am_sk_42424242',
});

const { data } = await autumn.attach({
  customer_id: "user_123",
  product_id: "pay_as_you_go",
  setup_payment: true,
  success_url: "https://your-app.com/settings",
});

if (data.url) {
  // Redirect user to Stripe setup page
}
```

```python
import asyncio
from autumn import Autumn

autumn = Autumn("am_sk_42424242")

async def main():
    response = await autumn.attach(
        customer_id="user_123",
        product_id="pay_as_you_go",
        setup_payment=True,
        success_url="https://your-app.com/settings",
    )
    
    if response.url:
        # Redirect user to Stripe setup page
        pass

asyncio.run(main())
```

```bash
curl -X POST "https://api.useautumn.com/v1/attach" \
  -H "Authorization: Bearer am_sk_42424242" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_123",
    "product_id": "pay_as_you_go",
    "setup_payment": true,
    "success_url": "https://your-app.com/settings"
  }'
```

--------------------------------

### Orchestrator Configuration Example

Source: https://github.com/useautumn/autumn/blob/dev/scripts/dw/README.md

Example configuration for orchestrators like Conductor or Superset, defining setup, run, and teardown commands for managing workspaces. These commands are executed automatically based on workspace lifecycle events.

```json
{
  "setup": ["bun dw setup"],
  "run": ["bun dw run"],
  "teardown": ["bun dw teardown"]
}
```

--------------------------------

### Run Autumn Development Server

Source: https://github.com/useautumn/autumn/blob/dev/README.md

Start the Autumn development server. This command is used after installing dependencies for self-hosting.

```bash
bun dev
```

--------------------------------

### Get Plan Response Example

Source: https://github.com/useautumn/autumn/blob/dev/apps/docs/mintlify/api-reference/plans/getPlan.mdx

This JSON object represents a successful response when retrieving details for a specific plan. It includes pricing information, included features, and metadata.

```json
{
  "id": "pro",
  "name": "Pro Plan",
  "description": null,
  "group": null,
  "version": 1,
  "addOn": false,
  "autoEnable": false,
  "price": {
    "amount": 10,
    "interval": "month",
    "display": {
      "primaryText": "$10",
      "secondaryText": "per month"
    }
  },
  "items": [
    {
      "featureId": "messages",
      "included": 100,
      "unlimited": false,
      "reset": {
        "interval": "month"
      },
      "price": {
        "amount": 0.5,
        "interval": "month",
        "billingUnits": 100,
        "billingMethod": "usage_based",
        "maxPurchase": null
      },
      "display": {
        "primaryText": "100 messages",
        "secondaryText": "then $0.5 per 100 messages"
      }
    },
    {
      "featureId": "users",
      "included": 0,
      "unlimited": false,
      "reset": null,
      "price": {
        "amount": 10,
        "interval": "month",
        "billingUnits": 1,
        "billingMethod": "prepaid",
        "maxPurchase": null
      },
      "display": {
        "primaryText": "$10 per Users"
      }
    }
  ],
  "createdAt": 1771513979217,
  "env": "sandbox",
  "archived": false,
  "baseVariantId": null,
  "config": {
    "ignore_past_due": false
  },
  "billing_controls": {},
  "metadata": {}
}
```

--------------------------------

### Apply Migrations in CI Pipeline

Source: https://github.com/useautumn/autumn/blob/dev/scripts/db/README.md

Example of a CI step to apply database migrations. This should be placed after the build step and before traffic shifting. The CI runner needs Infisical installed and authenticated.

```yaml
- name: Apply DB migrations
  run: bun db migrate --env=prod
```

--------------------------------

### Triggering a Dialog with shadcn/ui

Source: https://github.com/useautumn/autumn/blob/dev/apps/website/content/blog/shadcn.mdx

Example of how to trigger a custom dialog component (e.g., for plan changes) when a button is clicked within a shadcn/ui setup. The dialog component must be explicitly passed.

```jsx
//upgrading to Pro tier
<Button
  onClick={async () =>
    await attach({
      productId: "pro",
      dialog: ProductChangeDialog,
    })
  }
/>;
```

--------------------------------

### Run Development Server

Source: https://github.com/useautumn/autumn/blob/dev/apps/website/README.md

Use one of these commands to start the Next.js development server. Open http://localhost:3000 to view the application.

```bash
npm run dev
```

```bash
yarn dev
```

```bash
pnpm dev
```

```bash
bun dev
```

--------------------------------

### Setup Dev Worktree

Source: https://github.com/useautumn/autumn/blob/dev/scripts/dw/README.md

Provisions the worktree (DB branch, Docker services, env files) without starting the dev server. Use when an orchestrator manages the dev server process.

```sh
bun dw setup
```

--------------------------------

### Run the Application

Source: https://github.com/useautumn/autumn/blob/dev/CURSOR.md

Launches the full development stack for the application. This command bypasses Infisical and uses local environment variables. It starts the server, Vite, checkout, workers, and other services.

```bash
bun scripts/dw/index.ts
```

--------------------------------

### Drizzle Migration CLI Help

Source: https://github.com/useautumn/autumn/blob/dev/scripts/db/README.md

Prints the usage instructions for the `bun db` command and its subcommands.

```bash
bun db help
```

--------------------------------

### Create and Fetch Referral Code with useReferrals

Source: https://github.com/useautumn/autumn/blob/dev/apps/docs/mintlify/react/hooks/useReferrals.mdx

Use this snippet to get a referral code for the current customer. Call `refetch()` to initiate the creation or fetching process. The hook starts with `enabled: false` by default.

```tsx
import { useReferrals } from "autumn-js/react";

export default function ReferralCode() {
  const { data, refetch, isLoading } = useReferrals({ programId: "refer-a-friend" });

  return (
    <div>
      <button onClick={() => refetch()}>Get My Referral Code</button>
      {data && <p>Share this code: {data.code}</p>}
    </div>
  );
}
```

--------------------------------

### Attach Customer with Resetting Usage

Source: https://github.com/useautumn/autumn/blob/dev/apps/docs/mintlify/documentation/modelling-pricing/trials.mdx

This example demonstrates how to attach a customer to a plan and configure specific features to reset their usage when the trial period ends and billing begins. This ensures the customer receives a fresh allowance of features upon starting their paid subscription.

```APIDOC
## POST /v1/attach

### Description
Attaches a customer to a plan, with options to configure trial transition rules.

### Method
POST

### Endpoint
/v1/attach

### Parameters
#### Request Body
- **customer_id** (string) - Required - The ID of the customer.
- **plan_id** (string) - Required - The ID of the plan to attach the customer to.
- **transition_rules** (object) - Optional - Rules for transitioning from a trial to a paid plan.
  - **reset_after_trial_end** (array of strings) - Optional - A list of feature IDs whose usage should be reset when the trial ends.
```

```typescript
await autumn.attach({
  customerId: "user_123",
  planId: "pro",
  transitionRules: {
    resetAfterTrialEnd: ["messages"],
  },
});
```

```python
await autumn.attach(
    customer_id="user_123",
    plan_id="pro",
    transition_rules={
        "reset_after_trial_end": ["messages"],
    },
)
```

```curl
curl -X POST "https://api.useautumn.com/v1/attach" \
  -H "Authorization: Bearer am_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "user_123", "plan_id": "pro", "transition_rules": { "reset_after_trial_end": ["messages"] } }'
```

--------------------------------

### Install Autumn SDK

Source: https://github.com/useautumn/autumn/blob/dev/apps/docs/mintlify/documentation/getting-started/setup.mdx

Install the Autumn JavaScript SDK using your preferred package manager. Ensure the SDK is installed in both your backend and frontend if they are separate.

```bash
bun add autumn-js
```

```bash
npm install autumn-js
```

```bash
pnpm add autumn-js
```

```bash
yarn add autumn-js
```

--------------------------------

### Initialize Autumn project configuration

Source: https://github.com/useautumn/autumn/blob/dev/apps/docs/mintlify/cli/commands.mdx

Creates a new `autumn.config.ts` file using a starter template. Prompts for login if authentication is not yet set up.

```bash
atmn init
```

--------------------------------

### Install atmn CLI

Source: https://github.com/useautumn/autumn/blob/dev/packages/atmn/readme.md

Install the atmn CLI globally using npm. Alternatively, you can run commands directly using npx without a global installation.

```bash
npm install -g atmn
```

```bash
npx atmn <command>
```

--------------------------------

### Setup Payment Method (Python)

Source: https://github.com/useautumn/autumn/blob/dev/apps/docs/mintlify/examples/trial-card-not-required.mdx

Call the `setup_payment` method from the `autumn-sdk` to provide customers with a secure way to add their payment information. This prepares them for automatic billing once their trial period concludes.

```python
from autumn_sdk import Autumn

autumn = Autumn("am_sk_test_1234")

response = await autumn.billing.setup_payment(
    customer_id="user_123",
    success_url="https://your-app.com/success",
)
```

--------------------------------

### Configure Add-On Plans

Source: https://github.com/useautumn/autumn/blob/dev/apps/docs/mintlify/documentation/modelling-pricing/add-ons.mdx

Define add-on plans by setting `addOn: true` in your plan configuration. This example shows how to set up an 'Extra Storage' add-on with a metered feature and a 'Credit Top-Up' add-on with a prepaid billing method.

```typescript
import {
  feature,
  item,
  plan,
} from 'atmn';

export const storage = feature({
  id: 'storage',
  name: 'Storage (GB)',
  type: 'metered',
  consumable: false,
});

export const credits = feature({
  id: 'credits',
  name: 'Credits',
  type: 'metered',
  consumable: true,
});

export const storageAddOn = plan({
  id: 'storage_add_on',
  name: 'Extra Storage',
  addOn: true,
  price: { amount: 5, interval: 'month' },
  items: [
    item({
      featureId: storage.id,
      included: 100,
    }),
  ],
});

export const creditTopUp = plan({
  id: 'credit_top_up',
  name: 'Credit Top-Up',
  addOn: true,
  items: [
    item({
      featureId: credits.id,
      price: {
        amount: 10,
        billingUnits: 500,
        billingMethod: 'prepaid',
      },
    }),
  ],
});
```

--------------------------------

### Basic Script Structure

Source: https://github.com/useautumn/autumn/blob/dev/apps/website/content/blog/coding-agents-and-abstractions.mdx

A minimal example of a Scripts-v2 entrypoint file. It demonstrates basic configuration and the use of `s.step()` for defining script phases.

```typescript
import { AutumnContext, AutumnScript } from "@autumn/core";

const script: AutumnScript = {
  id: "my-script-id",
  org: "my-org",
  env: "dev",
  dryRun: true,
  params: {
    // Tunable parameters for the script
  },
  stores: {
    // Data stores for input/output
  },
  run: async (ctx: AutumnContext) => {
    await ctx.s.step("Phase 1", async () => {
      ctx.logger.info("Running phase 1...");
      // ... implementation ...
    });
  },
};

export default script;

```