npm package: @landofassets/sdk
Description: SDK for Land of Assets REST API
Author: Land of Assets
Latest version: 1.5.0

# @landofassets/sdk

Official SDK for the [Land of Assets](https://landofassets.com) REST API.

## Installation

```bash
npm install @landofassets/sdk
# or
pnpm add @landofassets/sdk
# or
yarn add @landofassets/sdk
```

## Quick Start

The SDK uses a **functional approach** - all API operations are exported as standalone functions that take a client instance as their first parameter.

```typescript
import { createSecretTokenInstance, listAssets, getAsset } from '@landofassets/sdk';

const orgName = 'my-org';
const projectName = 'my-project';

// Create a client instance (host defaults to https://api.landofassets.com)
const client = createSecretTokenInstance({
  secretToken: 'your-api-token',
});

// List assets
const assets = await listAssets(client, {
  query: { orgName, projectName },
});

// Get a specific asset
const asset = await getAsset(client, {
  params: { orgName, projectName, assetName: 'my-asset' },
});
```

## Features

- **Functional API design** - All operations are exported as standalone functions
- Full TypeScript support with complete type definitions
- Zod schema validation for requests and responses
- Axios-based HTTP client with automatic error handling
- Support for all Land of Assets API endpoints:
  - Assets and asset versions
  - Organizations and projects
  - Users and authentication
  - Comments and notifications
  - File uploads and downloads
  - API tokens and service accounts

## Uploading Assets

The SDK provides a simple helper function for uploading files. Here's a complete example:

```typescript
import { readFile } from 'node:fs/promises';
import { basename } from 'node:path';
import { createSecretTokenInstance, uploadFile, createAsset } from '@landofassets/sdk';

const orgName = 'my-org';
const projectName = 'my-project';

const client = createSecretTokenInstance({
  secretToken: 'your-api-token',
});

// Read the file and extract filename
const fileData = await readFile('model.glb');
const filename = basename('model.glb');

// Upload the file (infers MIME type and uploads)
const uploadToken = await uploadFile(client, {
  params: { orgName, projectName },
  fileData,
  filename,
});

// Create the asset record with the upload token
const asset = await createAsset(client, {
  params: { orgName, projectName },
  body: {
    name: 'My 3D Model',
    description: 'A beautiful 3D model',
    type: 'MODEL',
    uploadToken,
    visibility: 'PUBLIC',
    shareLicense: 'CC_BY',
  },
});
```

The `uploadFile` helper:

- Accepts file data (Buffer or Uint8Array) and filename
- Infers the MIME type from the file extension
- Prepares the upload and gets a signed URL
- Uploads the file to the signed URL
- Returns the upload token for use in `createAsset`

**Note:** In Node.js environments, you'll need to read the file yourself using `readFile` from `node:fs/promises` before calling `uploadFile`. In browser environments, you can pass a `File` object directly to `uploadFileToUploadUrl()` or convert it to an `ArrayBuffer`/`Uint8Array` for `uploadFile`.

For more control, you can use `prepareAssetUpload()` and `uploadFileToUploadUrl()` directly.

## API Reference

### Client Configuration

The SDK provides several client creation functions depending on your authentication method:

```typescript
import {
  createSecretTokenInstance, // For API tokens (most common)
  createFrontendTokenInstance, // For frontend tokens
  createSessionInstance, // For user sessions
  createAnonymousClient, // For anonymous access
} from '@landofassets/sdk';

// Most common: API token authentication
// host defaults to 'https://api.landofassets.com' if not provided
const client = createSecretTokenInstance({
  secretToken: 'your-api-token',
  // host: 'https://api.landofassets.com', // Optional, defaults to production API
});
```

**Note:** For normal users, you typically don't need to specify the `host` parameter as it defaults to `https://api.landofassets.com`. Only internal developers may need to override this for testing against different environments.

### Available Functions

The SDK exports functions for all API operations. Here are the main categories:

**Assets:**

- `listAssets()` - List assets in a project
- `getAsset()` - Get asset metadata
- `createAsset()` - Create a new asset
- `updateAsset()` - Update asset metadata
- `deleteAsset()` - Delete an asset
- `uploadFile()` - Upload a file and get upload token (helper function)
- `prepareAssetUpload()` - Get signed upload URL and token
- `uploadFileToUploadUrl()` - Upload file to signed URL

**Organizations:**

- `listOrgs()` - List organizations
- `getOrg()` - Get organization details
- `createOrg()` - Create an organization
- `updateOrg()` - Update organization
- `deleteOrg()` - Delete an organization

**Projects:**

- `listProjects()` - List projects in an organization
- `getProject()` - Get project details
- `createProject()` - Create a project
- `updateProject()` - Update project
- `deleteProject()` - Delete a project

**Other resources:**

- Users, authentication, comments, notifications
- API tokens, service accounts
- Organization members and member invites

All functions follow the pattern: `functionName(client, props)` where `client` is the API client instance and `props` contains the request parameters.

## Zod Schemas

The SDK exports Zod schemas for all API request and response types, enabling runtime validation:

```typescript
import { assetSchema, createAssetBodySchema } from '@landofassets/sdk';

// Validate an asset object
const validatedAsset = assetSchema.parse(assetData);

// Validate create asset input
const validatedInput = createAssetBodySchema.parse(createAssetInput);
```

## Requirements

- Node.js >= 23.0.0

## License

MIT