Documentation: 0.5.0 (source: v0.5.0).
# cargo

Markdown source of https://docs-v0-5-0.atlas-kit-docs.pages.dev/reference/cargo/ — see https://docs-v0-5-0.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

## Interfaces

<a id="cargocapacity"></a>

### CargoCapacity

Defined in: [packages/sage/src/internal/cargo.ts:43](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/internal/cargo.ts#L43)

Exact used, total, remaining, and excess values for one capacity axis.

#### Example

```ts
declare const capacity: CargoCapacity;
console.log(capacity.remainingRaw);
```

#### Properties

<a id="overcapacityraw"></a>

##### overCapacityRaw

```ts
readonly overCapacityRaw: bigint;
```

Defined in: [packages/sage/src/internal/cargo.ts:47](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/internal/cargo.ts#L47)

<a id="remainingraw"></a>

##### remainingRaw

```ts
readonly remainingRaw: bigint;
```

Defined in: [packages/sage/src/internal/cargo.ts:46](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/internal/cargo.ts#L46)

<a id="totalraw"></a>

##### totalRaw

```ts
readonly totalRaw: bigint;
```

Defined in: [packages/sage/src/internal/cargo.ts:45](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/internal/cargo.ts#L45)

<a id="usedraw"></a>

##### usedRaw

```ts
readonly usedRaw: bigint;
```

Defined in: [packages/sage/src/internal/cargo.ts:44](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/internal/cargo.ts#L44)

***

<a id="cargoinventoryitem"></a>

### CargoInventoryItem

Defined in: [packages/sage/src/internal/cargo.ts:17](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/internal/cargo.ts#L17)

Exact cargo quantity joined to its lazily loaded definition.

#### Example

```ts
declare const item: CargoInventoryItem;
console.log(item.name, item.quantityRaw);
```

#### Extends

- [`CargoDefinitionSummary`](/reference/#cargodefinitionsummary)

#### Properties

<a id="categoryid"></a>

##### categoryId

```ts
readonly categoryId: number;
```

Defined in: [packages/sage/src/registry/index.ts:69](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/registry/index.ts#L69)

###### Inherited from

[`CargoDefinitionSummary`](/reference/#cargodefinitionsummary).[`categoryId`](/reference/#cargodefinitionsummary)

<a id="id"></a>

##### id

```ts
readonly id: number;
```

Defined in: [packages/sage/src/registry/index.ts:70](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/registry/index.ts#L70)

###### Inherited from

[`CargoDefinitionSummary`](/reference/#cargodefinitionsummary).[`id`](/reference/#cargodefinitionsummary)

<a id="mint"></a>

##### mint

```ts
readonly mint: Address;
```

Defined in: [packages/sage/src/registry/index.ts:71](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/registry/index.ts#L71)

###### Inherited from

[`CargoDefinitionSummary`](/reference/#cargodefinitionsummary).[`mint`](/reference/#cargodefinitionsummary)

<a id="name"></a>

##### name

```ts
readonly name: string;
```

Defined in: [packages/sage/src/registry/index.ts:72](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/registry/index.ts#L72)

###### Inherited from

[`CargoDefinitionSummary`](/reference/#cargodefinitionsummary).[`name`](/reference/#cargodefinitionsummary)

<a id="quantityraw"></a>

##### quantityRaw

```ts
readonly quantityRaw: bigint;
```

Defined in: [packages/sage/src/internal/cargo.ts:19](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/internal/cargo.ts#L19)

Exact on-chain cargo quantity in the cargo type's raw units.

<a id="storagecost"></a>

##### storageCost

```ts
readonly storageCost: number;
```

Defined in: [packages/sage/src/registry/index.ts:73](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/registry/index.ts#L73)

###### Inherited from

[`CargoDefinitionSummary`](/reference/#cargodefinitionsummary).[`storageCost`](/reference/#cargodefinitionsummary)

***

<a id="cargopodinventory"></a>

### CargoPodInventory

Defined in: [packages/sage/src/internal/cargo.ts:29](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/internal/cargo.ts#L29)

One nested C4 CargoPod translated into an immutable inventory value.

#### Example

```ts
declare const pod: CargoPodInventory;
console.log(pod.usedStorageUnitsRaw, pod.items);
```

#### Properties

<a id="items"></a>

##### items

```ts
readonly items: readonly CargoInventoryItem[];
```

Defined in: [packages/sage/src/internal/cargo.ts:33](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/internal/cargo.ts#L33)

<a id="sequenceid"></a>

##### sequenceId

```ts
readonly sequenceId: number;
```

Defined in: [packages/sage/src/internal/cargo.ts:30](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/internal/cargo.ts#L30)

<a id="usedstorageunitsraw"></a>

##### usedStorageUnitsRaw

```ts
readonly usedStorageUnitsRaw: bigint;
```

Defined in: [packages/sage/src/internal/cargo.ts:32](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/internal/cargo.ts#L32)

Exact aggregate storage use reported by the parent account.

***

<a id="fleetcargoinventorysnapshot"></a>

### FleetCargoInventorySnapshot

Defined in: [packages/sage/src/cargo/index.ts:73](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/cargo/index.ts#L73)

Immutable cargo inventory projected from the CargoPods nested in a Fleet.

#### Example

```ts
declare const inventory: FleetCargoInventorySnapshot;
console.log(inventory.cargoHold.items);
```

#### Extends

- `Omit`\<`ResolvedFleetCargoInventory`, `"ownerProfile"`\>

#### Extended by

- [`FleetCargoInventoryView`](/reference/#fleetcargoinventoryview)

#### Properties

<a id="address"></a>

##### address

```ts
readonly address: Address;
```

Defined in: [packages/sage/src/cargo/index.ts:79](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/cargo/index.ts#L79)

Parent Fleet address; CargoPods are nested values and have no own address.

<a id="ammo"></a>

##### ammo

```ts
readonly ammo: CargoInventoryItem;
```

Defined in: [packages/sage/src/internal/cargo.ts:63](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/internal/cargo.ts#L63)

###### Inherited from

```ts
Omit.ammo
```

<a id="capacities"></a>

##### capacities

```ts
readonly capacities: {
  ammoUnits: CargoCapacity;
  cargoStorageUnits: CargoCapacity;
  fuelUnits: CargoCapacity;
};
```

Defined in: [packages/sage/src/internal/cargo.ts:64](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/internal/cargo.ts#L64)

###### ammoUnits

```ts
readonly ammoUnits: CargoCapacity;
```

###### cargoStorageUnits

```ts
readonly cargoStorageUnits: CargoCapacity;
```

###### fuelUnits

```ts
readonly fuelUnits: CargoCapacity;
```

###### Inherited from

```ts
Omit.capacities
```

<a id="cargohold"></a>

##### cargoHold

```ts
readonly cargoHold: CargoPodInventory;
```

Defined in: [packages/sage/src/internal/cargo.ts:59](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/internal/cargo.ts#L59)

###### Inherited from

```ts
Omit.cargoHold
```

<a id="components"></a>

##### components

```ts
readonly components: CargoPodInventory;
```

Defined in: [packages/sage/src/internal/cargo.ts:60](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/internal/cargo.ts#L60)

###### Inherited from

```ts
Omit.components
```

<a id="fleet"></a>

##### fleet

```ts
readonly fleet: EntityRef<"fleet">;
```

Defined in: [packages/sage/src/cargo/index.ts:80](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/cargo/index.ts#L80)

<a id="fuel"></a>

##### fuel

```ts
readonly fuel: CargoInventoryItem;
```

Defined in: [packages/sage/src/internal/cargo.ts:62](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/internal/cargo.ts#L62)

###### Inherited from

```ts
Omit.fuel
```

<a id="kind"></a>

##### kind

```ts
readonly kind: "fleetCargoInventory";
```

Defined in: [packages/sage/src/cargo/index.ts:77](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/cargo/index.ts#L77)

<a id="ownerprofile"></a>

##### ownerProfile

```ts
readonly ownerProfile: EntityRef<"profile">;
```

Defined in: [packages/sage/src/cargo/index.ts:81](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/cargo/index.ts#L81)

<a id="respawningcargo"></a>

##### respawningCargo

```ts
readonly respawningCargo: CargoPodInventory;
```

Defined in: [packages/sage/src/internal/cargo.ts:61](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/internal/cargo.ts#L61)

###### Inherited from

```ts
Omit.respawningCargo
```

#### Methods

<a id="tojson"></a>

##### toJSON()

```ts
toJSON(): unknown;
```

Defined in: [packages/sage/src/cargo/index.ts:82](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/cargo/index.ts#L82)

###### Returns

`unknown`

## Type Aliases

<a id="cargodefinition"></a>

### CargoDefinition

```ts
type CargoDefinition = CargoDefinitionSummary;
```

Defined in: [packages/sage/src/cargo/index.ts:45](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/cargo/index.ts#L45)

Stable cargo definition resolved lazily from the configured Game registry.

#### Example

```ts
declare const definition: CargoDefinition;
console.log(definition.name, definition.storageCost);
```

***

<a id="cargodefinitionlookupoptions"></a>

### CargoDefinitionLookupOptions

```ts
type CargoDefinitionLookupOptions = DefinitionLookupOptions;
```

Defined in: [packages/sage/src/cargo/index.ts:53](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/cargo/index.ts#L53)

Sequence expectation used when resolving a cargo definition.

#### Example

```ts
const options: CargoDefinitionLookupOptions = { expectedSequenceId: 4 };
```

***

<a id="cargodiscoveryoptions"></a>

### CargoDiscoveryOptions

```ts
type CargoDiscoveryOptions = Omit<DiscoveryRequest, "filters" | "strategy">;
```

Defined in: [packages/sage/src/cargo/index.ts:61](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/cargo/index.ts#L61)

Options supported by targeted Fleet cargo inventory discovery.

#### Example

```ts
const options: CargoDiscoveryOptions = { commitment: 'confirmed' };
```

## Functions

<a id="getcargodefinition"></a>

### getCargoDefinition()

```ts
function getCargoDefinition(
   context, 
   cargoId, 
options?): Promise<CargoDefinitionSummary>;
```

Defined in: [packages/sage/src/cargo/index.ts:162](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/cargo/index.ts#L162)

Resolves one cargo definition without loading the Game registry eagerly.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `context` | [`SageContext`](/reference/#sagecontext) |
| `cargoId` | `number` |
| `options?` | [`DefinitionLookupOptions`](/reference/#definitionlookupoptions) |

#### Returns

`Promise`\<[`CargoDefinitionSummary`](/reference/#cargodefinitionsummary)\>

#### Example

```ts
declare const ctx: SageContext;
const fuel = await getCargoDefinition(ctx, 1);
```

***

<a id="getfleetcargoinventoriesbyowner"></a>

### getFleetCargoInventoriesByOwner()

```ts
function getFleetCargoInventoriesByOwner(
   context, 
   profileAddress, 
options?): Promise<readonly FleetCargoInventorySnapshot[]>;
```

Defined in: [packages/sage/src/cargo/index.ts:227](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/cargo/index.ts#L227)

Discovers CargoPod inventories for Fleets owned by a Player Profile.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `context` | [`SageContext`](/reference/#sagecontext) |
| `profileAddress` | [`Address`](/reference/#address-19) |
| `options?` | [`CargoDiscoveryOptions`](/reference/cargo/#cargodiscoveryoptions) |

#### Returns

`Promise`\<readonly [`FleetCargoInventorySnapshot`](/reference/cargo/#fleetcargoinventorysnapshot)[]\>

#### Example

```ts
declare const ctx: SageContext;
declare const profileAddress: Address;
const inventories = await getFleetCargoInventoriesByOwner(ctx, profileAddress);
```

***

<a id="getfleetcargoinventory"></a>

### getFleetCargoInventory()

```ts
function getFleetCargoInventory(
   context, 
   fleetAddress, 
options?): Promise<FleetCargoInventorySnapshot>;
```

Defined in: [packages/sage/src/cargo/index.ts:178](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/cargo/index.ts#L178)

Reads the required CargoPods nested in a Fleet account.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `context` | [`SageContext`](/reference/#sagecontext) |
| `fleetAddress` | [`Address`](/reference/#address-19) |
| `options?` | [`ReadOptions`](/reference/client/#readoptions) |

#### Returns

`Promise`\<[`FleetCargoInventorySnapshot`](/reference/cargo/#fleetcargoinventorysnapshot)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleetAddress: Address;
const inventory = await getFleetCargoInventory(ctx, fleetAddress);
```

***

<a id="maybegetfleetcargoinventory"></a>

### maybeGetFleetCargoInventory()

```ts
function maybeGetFleetCargoInventory(
   context, 
   fleetAddress, 
   options?): Promise<
  | FleetCargoInventorySnapshot
| undefined>;
```

Defined in: [packages/sage/src/cargo/index.ts:202](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/cargo/index.ts#L202)

Reads optional CargoPods nested in a Fleet account.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `context` | [`SageContext`](/reference/#sagecontext) |
| `fleetAddress` | [`Address`](/reference/#address-19) |
| `options?` | [`ReadOptions`](/reference/client/#readoptions) |

#### Returns

`Promise`\<
  \| [`FleetCargoInventorySnapshot`](/reference/cargo/#fleetcargoinventorysnapshot)
  \| `undefined`\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleetAddress: Address;
const inventory = await maybeGetFleetCargoInventory(ctx, fleetAddress);
```