# Start SDK

The Start SDK (`@start9labs/start-sdk`) is a TypeScript framework for packaging services to run on [StartOS](https://github.com/Start9Labs/start-os). It provides a strongly-typed, builder-pattern API for defining every aspect of a service package: manifests, daemons, health checks, networking interfaces, actions, backups, dependencies, configuration, and more.

## Features

- **Type-safe manifest definitions** - Declare your service's identity, metadata, images, volumes, and dependencies with full TypeScript inference.
- **Daemon management** - Define multi-process topologies with startup ordering, ready probes, and graceful shutdown via `Daemons.of().addDaemon()`.
- **Health checks** - Built-in checks for TCP port listening, HTTP(S) endpoints, and custom scripts, with configurable polling strategies (fixed interval, cooldown, adaptive).
- **Network interfaces** - Bind ports, export UI/API/P2P interfaces, and manage hostnames with MultiHost and ServiceInterfaceBuilder.
- **User actions** - Create interactive operations with validated form inputs (text, select, toggle, list, union/variants, and more) that users can trigger from the StartOS UI.
- **Backup and restore** - Rsync-based volume backups with exclude patterns and custom sync paths.
- **Dependency management** - Declare inter-service dependencies with version ranges, health check requirements, and volume mounts.
- **Configuration file helpers** - Read, write, and merge JSON, YAML, TOML, INI, and ENV files with type-safe `FileHelper`.
- **Reactive subscriptions** - Watch for changes to container IPs, SSL certificates, SMTP config, service status, and more with `const()`, `once()`, `watch()`, `onChange()`, and `waitFor()` patterns.
- **Extended versioning (ExVer)** - Flavor-aware semantic versioning with range matching, supporting independent upstream and downstream version tracking.
- **Internationalization** - Built-in i18n support with locale fallback and parameter substitution.
- **Container execution** - Run commands in subcontainers with volume mounts, environment variables, and entrypoint overrides.
- **Plugin system** - Extensible plugin architecture (e.g. `url-v0` for URL management).

## Quick Start

```typescript
import { setupManifest, buildManifest } from '@start9labs/start-sdk'

const manifest = setupManifest({
  id: 'my-service',
  title: 'My Service',
  license: 'MIT',
  // ...
})

export default buildManifest(manifest)
```

The primary entry point is the `StartSdk` facade:

```typescript
import { StartSdk } from '@start9labs/start-sdk'
import { manifest } from './manifest'

export const sdk = StartSdk.of().withManifest(manifest).build(true)
```

From there, `sdk` exposes the full toolkit:

```typescript
// Define daemons
export const main = sdk.setupMain(async ({ effects }) =>
  sdk.Daemons.of(effects)
    .addDaemon('primary', { /* ... */ })
)

// Define actions
export const setName = sdk.Action.withInput('set-name', /* ... */)

// Define interfaces
export const setInterfaces = sdk.setupInterfaces(async ({ effects }) => {
  const multi = sdk.MultiHost.of(effects, 'web')
  const origin = await multi.bindPort(80, { protocol: 'http' })
  const ui = sdk.createInterface(effects, { name: 'Web UI', id: 'ui', /* ... */ })
  return [await origin.export([ui])]
})

// Define backups
export const { createBackup, restoreBackup } = sdk.setupBackups(
  async () => sdk.Backups.ofVolumes('main')
)
```

## Packages

| Package | npm | Description |
|---------|-----|-------------|
| `package/` | `@start9labs/start-sdk` | Full SDK for service developers |
| `base/` | `@start9labs/start-sdk-base` | Core types, ABI definitions, and effects interface |

## Documentation

For comprehensive packaging guides, tutorials, and API reference:

**[docs.start9.com/packaging](https://docs.start9.com/packaging)**

The packaging docs cover:
- Environment setup and prerequisites
- Project structure and conventions
- Manifest, main, interfaces, actions, and all other service modules
- File models and configuration management
- Versioning, migrations, and initialization
- Dependencies and cross-service communication
- Building and installing `.s9pk` packages

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for environment setup, building from source, testing, and development workflow.

## Architecture

See [ARCHITECTURE.md](ARCHITECTURE.md) for a detailed overview of the SDK's internal structure, module responsibilities, and data flow.

## License

MIT