> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metabind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Packages Overview

> Packages create immutable snapshots of all components for versioned distribution

# Packages

Packages enable version control and dependency management at the project level by creating immutable snapshots of all components and their bound assets at a specific point in time. Each package uses semantic versioning and can be referenced by other projects.

## Key Concepts

| Concept                   | Description                                                |
| ------------------------- | ---------------------------------------------------------- |
| **Immutable Snapshots**   | Packages cannot be modified after creation                 |
| **Semantic Versioning**   | Uses MAJOR.MINOR.PATCH format (e.g., `1.0.0`)              |
| **Auto-Publishing**       | Creating a package publishes all draft/modified components |
| **Asset Bundling**        | All component-bound assets are included                    |
| **Dependency Resolution** | Project dependencies are snapshotted                       |

## What Happens When You Create a Package

1. **Draft components** (never published) → `published` status with version 1
2. **Modified components** → `published` status with incremented version
3. **Published components** (unchanged) → included at current version
4. **Collection structure** is flattened (not preserved in packages)
5. **All bound assets** are captured and included

## Package Object

### Fields

| Field                  | Type      | Description                             |
| ---------------------- | --------- | --------------------------------------- |
| `id`                   | string    | Unique identifier (UUID)                |
| `projectId`            | string    | Source project ID                       |
| `version`              | string    | Semantic version (e.g., `1.0.0`)        |
| `components`           | object\[] | Array of component snapshots            |
| `components[].id`      | string    | Component ID                            |
| `components[].name`    | string    | Component name                          |
| `components[].type`    | string    | `view` or `layout`                      |
| `components[].version` | number    | Component version at time of capture    |
| `assets`               | object\[] | Array of bundled assets                 |
| `assets[].id`          | string    | Asset ID                                |
| `assets[].name`        | string    | Asset friendly name                     |
| `assets[].url`         | string    | CDN URL                                 |
| `assets[].componentId` | string    | Owning component ID                     |
| `dependencies`         | object\[] | Snapshotted project dependencies        |
| `compiled`             | object    | Runtime-ready content                   |
| `compiled.components`  | object    | Map of component names to compiled code |
| `compiled.assets`      | object    | Map of component names to asset arrays  |
| `metadata`             | object    | Package metadata                        |
| `metadata.author`      | string    | Creator                                 |
| `metadata.description` | string    | Package description                     |
| `metadata.tags`        | string\[] | Categories                              |
| `createdAt`            | string    | Creation timestamp                      |
| `updatedAt`            | string    | Last update timestamp                   |

### Example Package

```json theme={null}
{
  "id": "pkg123",
  "projectId": "proj123",
  "version": "1.0.0",
  "components": [
    {
      "id": "comp123",
      "name": "ProductCard",
      "type": "view",
      "version": 5
    },
    {
      "id": "comp124",
      "name": "ArticleLayout",
      "type": "layout",
      "version": 2
    }
  ],
  "assets": [
    {
      "id": "asset123",
      "name": "logo-primary",
      "url": "https://cdn.metabind.ai/assets/logo-2x.png",
      "componentId": "comp123"
    }
  ],
  "compiled": {
    "components": {
      "ProductCard": "const body = (props) => { ... }",
      "ArticleLayout": "const body = (props, children) => { ... }"
    },
    "assets": {
      "ProductCard": [
        { "name": "logo-primary", "url": "https://cdn.metabind.ai/assets/logo-2x.png" }
      ]
    }
  },
  "dependencies": [
    {
      "projectId": "proj456",
      "version": "2.0.0"
    }
  ],
  "metadata": {
    "author": "jane.doe@metabind.ai",
    "description": "Core UI components v1",
    "tags": ["ui", "core"]
  },
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-20T10:00:00Z"
}
```

## Package Creation Process

```mermaid theme={null}
graph TD
    A[Create Package Request] --> B[Identify Changed Components]
    B --> C[Assign New Version Numbers]
    C --> D[Update Component Status to Published]
    D --> E[Capture Bound Assets]
    E --> F[Snapshot Dependencies]
    F --> G[Create Immutable Package]
```

### Version Assignment

| Previous Status           | New Status  | Version Change |
| ------------------------- | ----------- | -------------- |
| `draft` (never published) | `published` | `null` → `1`   |
| `modified`                | `published` | `n` → `n+1`    |
| `published` (unchanged)   | `published` | No change      |

## Base URL

All package endpoints use this base path:

```
/app/v1/organizations/:organizationId/projects/:projectId/packages
```