@fractal_cloud/sdk 1.0.0 → 1.2.0

package/README.md

@@ -2,244 +2,261 @@
 
 [![NPM Version][npm-image]][npm-url]
 [![build status][build-image]][build-url]
+[![codecov][codecov-image]][codecov-url]
 [![license][license-image]](LICENSE)
 [![Known Vulnerabilities][snyk-image]][snyk-url]
-[![codecov][codecov-image]][codecov-url]
 [![TypeScript Style Guide][gts-image]][gts-url]
 
 ## Overview
 
-The Fractal TypeScript SDK is an early stage but production ready SDK that allows platform engineers and application developers to define cloud agnostic infrastructure blueprints using TypeScript.
-It is designed to bridge software architecture and infrastructure automation, enabling teams to express infrastructure intent in a general purpose language without relying on vendor specific tools or domain specific languages.
-With Fractal, infrastructure is no longer written as low level scripts. It is modeled as reusable architectural building blocks that can be validated, governed, and evolved over time.
-This SDK is currently at version 1.0.0. It supports Blueprint and Live System definition and deployment and is intended for early production pilots and platform experimentation.
-
-## Why Fractal
-
-Modern infrastructure automation forces teams to choose between flexibility and control.
-
-Traditional Infrastructure as Code approaches are:
-
-1. Tightly coupled to a specific cloud vendor
-2. Based on string heavy DSLs
-3. Difficult to govern at scale
-4. Focused on resources rather than architecture
-
-Fractal Cloud takes a different approach.
-
-Fractal Cloud allows you to:
-
-1. Define infrastructure as architecture, not scripts
-2. Use TypeScript instead of a DSL
-3. Encode governance and intent directly into reusable blueprints
-4. Remain cloud-agnostic by design
-
-This SDK is the programmatic interface to that model.
+The Fractal Cloud TypeScript SDK lets platform engineers and application developers define cloud-agnostic infrastructure blueprints in TypeScript and deploy them to any supported cloud provider.
 
-## Core concepts in one minute
+Infrastructure is modelled as reusable architectural building blocks — **Fractals** — that can be validated, governed, and evolved over time. Live Systems map those blueprints to concrete cloud resources without ever touching vendor-specific tooling or DSLs.
 
-You do not need prior knowledge of Fractal to use this SDK, the most important concepts are explained below.
+## Why Fractal
 
-### Fractal
+Traditional Infrastructure as Code forces a choice between flexibility and control:
 
-A Fractal is a governed, reusable infrastructure construct.
-It defines what an infrastructure system is allowed to be, not just what it deploys.
-It is composed by a Blueprint and an Interface.
+- Tightly coupled to a specific cloud vendor
+- String-heavy DSLs with no type safety
+- Hard to govern at scale
+- Focused on raw resources rather than architecture
 
-#### Blueprint
+Fractal Cloud takes a different approach: define infrastructure as **architecture**, stay cloud-agnostic by design, and let the Fractal Automation Engine handle provisioning and drift reconciliation.
 
-A Blueprint is the static definition of a Fractal.
-It describes components, their relationships, and their architectural intent.
+## Core concepts
 
-#### Interface
+### Fractal (Blueprint)
 
-An Interface is the versioned set of operations through which a Fractal can be specialized or extended. 
-These operations may involve the addition, removal, or modification of components and their integrations within the Fractal.
+A Fractal is a governed, reusable infrastructure pattern. It defines what an infrastructure system is allowed to be — components, their relationships, and architectural intent — without referencing any cloud provider. Fractals are registered with the Fractal Cloud API and can be composed into higher-order Fractals.
 
 ### Live System
 
-A Live System is a running instance of a Fractal deployed to a cloud environment.
-Live Systems are not yet supported in the TypeScript SDK.
-
-For a deeper explanation of Fractal Architecture, see the documentation linked below.
-
-## What this SDK does today
-
-Version 1.0.0 supports the following capabilities.
-
-* Definition of Fractal Blueprints
-* Deployment of Blueprints to Fractal Cloud
-* Definition of Live Systems
-* Deployment of Live Systems to a specified Fractal Cloud Environment
-* Usage from both personal and organization owned accounts
-
-This SDK does not yet support:
-
-* Fractal Interface definition
-* Bounded Context helpers
-* Environment helpers
-
-## Architectural positioning
-
-The Fractal TypeScript SDK acts as a bridge between software architecture and infrastructure automation.
-
-It allows teams to:
+A Live System is a running instance of a Fractal. It maps each abstract blueprint component to a concrete provider-specific **Offer** and supplies the vendor parameters the Fractal Automation Engine needs to provision and reconcile cloud resources. There are no state files — the cloud is the source of truth.
 
-* Describe infrastructure using architectural concepts
-* Keep infrastructure definitions vendor neutral
-* Rely on the Fractal Automation Engine to interpret and enforce those definitions
+## What this SDK supports
 
-This SDK does not replace cloud providers, nor does it expose raw infrastructure primitives.
-Instead, it defines intent and delegates execution to the Fractal Automation Engine.
-
-This is Infrastructure as Code without cloud-specific code.
+- Definition of Fractal Blueprints using cloud-agnostic component helpers
+- Deployment of Blueprints to Fractal Cloud
+- Definition of Live Systems with typed, provider-specific helpers
+- Deployment of Live Systems to any Fractal Cloud Environment
+- Personal and organisation-owned accounts
+- **IaaS helpers** for AWS, Azure, GCP, OCI, and Hetzner
+- **PaaS helpers** for AWS ECS (cluster, task definition, service)
 
 ## Installation
 
-The SDK is published as a public npm package.
-
 ```bash
 npm install @fractal_cloud/sdk
 ```
 
-[Package page](https://www.npmjs.com/package/@fractal_cloud/sdk)
+[Package page](https://www.npmjs.com/package/@fractal_cloud/sdk) · [Source repository](https://github.com/Fractal-Cloud/fractal-ts-sdk)
 
-[Source repository](https://github.com/Fractal-Cloud/fractal-ts-sdk)
+Requires Node.js 18+ and TypeScript 5+.
 
-Node.js and TypeScript requirements are documented in the repository and follow standard modern LTS versions.
+## Quick start
 
-## Minimal example
+The following example defines a cloud-agnostic blueprint with a VPC, a subnet, a security group, and two VMs — then deploys it on AWS.
 
-The following example defines and deploys the smallest useful Fractal Blueprint supported today.
+### 1. Define the blueprint (`fractal.ts`)
 
-It creates a Fractal with a single component and deploys the Blueprint to Fractal Cloud.
+```typescript
+import {
+  BoundedContext, Fractal, KebabCaseString, OwnerId, OwnerType, Version,
+  VirtualNetwork, Subnet, SecurityGroup, VirtualMachine,
+} from '@fractal_cloud/sdk';
 
-```js
-// The Bounded Context ID is used to group Blueprints and Live System in order to granularly control access within an Organization
 const bcId = BoundedContext.Id.getBuilder()
   .withOwnerType(OwnerType.Personal)
-  .withOwnerId(OwnerId.getBuilder()
-    .withValue("00000000-0000-0000-0000-000000000000")
-    .build())
-  .withName(KebabCaseString.getBuilder().withValue("test").build())
+  .withOwnerId(OwnerId.getBuilder().withValue(process.env['OWNER_ID']!).build())
+  .withName(KebabCaseString.getBuilder().withValue('my-team').build())
   .build();
 
-// Service account credentials are obtained from environment variables
-const serviceAccountCredentials = ServiceAccountCredentials.getBuilder()
-  .withId(ServiceAccountId.getBuilder().withValue(process.env['SERVICE_ACCOUNT_ID']).build())
-.withSecret(process.env['SERVICE_ACCOUNT_SECRET'])
-.build();
-
-// The Fractal is defined using the Builder pattern
-const fractal = Fractal.getBuilder()
-  .withId(Fractal.Id.getBuilder()
-    .withBoundedContextId(bcId)
-    .withName(KebabCaseString.getBuilder().withValue("fractal-from-ts").build())
-    .withVersion(Version.getBuilder().withMajor(1).withMinor(0).withPatch(0).build())
-    .build())
-  .withComponent(Fractal.Component.getBuilder()
-    .withId(Fractal.Component.Id.getBuilder()
-      .withValue(KebabCaseString.getBuilder().withValue("container-orchestrator").build())
-      .build())
-    .withVersion(Version.getBuilder().withMajor(1).withMinor(0).withPatch(0).build())
-    .withDescription("Container orchestrator for the fractal")
-    .withDisplayName("Container orchestrator")
-    .withType(Fractal.Component.Type.getBuilder()
-      .withInfrastructureDomain(InfrastructureDomain.NetworkAndCompute)
-      .withServiceDeliveryModel(ServiceDeliveryModel.PaaS)
-      .withName(PascalCaseString.getBuilder().withValue("Kubernetes").build())
-      .build())
-    .build())
+const apiServer = VirtualMachine.create({
+  id: 'api-server',
+  version: {major: 1, minor: 0, patch: 0},
+  displayName: 'API Server',
+});
+
+const webServer = VirtualMachine.create({
+  id: 'web-server',
+  version: {major: 1, minor: 0, patch: 0},
+  displayName: 'Web Server',
+}).withLinks([{target: apiServer, fromPort: 8080}]);
+
+const network = VirtualNetwork.create({
+  id: 'main-network',
+  version: {major: 1, minor: 0, patch: 0},
+  displayName: 'Main VPC',
+  cidrBlock: '10.0.0.0/16',
+})
+  .withSubnets([
+    Subnet.create({
+      id: 'public-subnet',
+      version: {major: 1, minor: 0, patch: 0},
+      displayName: 'Public Subnet',
+      cidrBlock: '10.0.1.0/24',
+    }).withVirtualMachines([webServer, apiServer]),
+  ])
+  .withSecurityGroups([
+    SecurityGroup.create({
+      id: 'web-sg',
+      version: {major: 1, minor: 0, patch: 0},
+      displayName: 'Web Security Group',
+      description: 'Allow SSH and HTTP',
+      ingressRules: [
+        {protocol: 'tcp', fromPort: 22, toPort: 22, sourceCidr: '0.0.0.0/0'},
+        {protocol: 'tcp', fromPort: 80, toPort: 80, sourceCidr: '0.0.0.0/0'},
+      ],
+    }),
+  ]);
+
+export const fractal = Fractal.getBuilder()
+  .withId(
+    Fractal.Id.getBuilder()
+      .withBoundedContextId(bcId)
+      .withName(KebabCaseString.getBuilder().withValue('my-iaas-fractal').build())
+      .withVersion(Version.getBuilder().withMajor(1).withMinor(0).withPatch(0).build())
+      .build(),
+  )
+  .withComponents([...network.components])
   .build();
+```
 
-// Blueprint deployment is initiated using the deploy method on the Fractal object
-await fractal.deploy(serviceAccountCredentials);
+### 2. Satisfy with AWS components (`aws_live_system.ts`)
+
+```typescript
+import {
+  AwsVpc, AwsSubnet, AwsSecurityGroup, Ec2Instance,
+  Environment, KebabCaseString, LiveSystem, OwnerId, OwnerType,
+} from '@fractal_cloud/sdk';
+import {bcId, fractal} from './fractal';
+
+function bp(id: string) {
+  const c = fractal.components.find(x => x.id.toString() === id);
+  if (!c) throw new Error(`Blueprint component '${id}' not found`);
+  return c;
+}
+
+export function getLiveSystem(): LiveSystem {
+  const vpc    = AwsVpc.satisfy(bp('main-network')).withEnableDnsSupport(true).build();
+  const subnet = AwsSubnet.satisfy(bp('public-subnet')).withAvailabilityZone('eu-central-1a').build();
+  const sg     = AwsSecurityGroup.satisfy(bp('web-sg')).build();
+  const web    = Ec2Instance.satisfy(bp('web-server')).withAmiId('ami-0c55b159cbfafe1f0').withInstanceType('t3.micro').build();
+  const api    = Ec2Instance.satisfy(bp('api-server')).withAmiId('ami-0c55b159cbfafe1f0').withInstanceType('t3.small').build();
+
+  return LiveSystem.getBuilder()
+    .withId(LiveSystem.Id.getBuilder().withBoundedContextId(bcId)
+      .withName(KebabCaseString.getBuilder().withValue('my-iaas-aws').build()).build())
+    .withFractalId(fractal.id)
+    .withGenericProvider('AWS')
+    .withEnvironment(Environment.getBuilder()
+      .withId(Environment.Id.getBuilder()
+        .withOwnerType(OwnerType.Personal)
+        .withOwnerId(OwnerId.getBuilder().withValue(process.env['OWNER_ID']!).build())
+        .withName(KebabCaseString.getBuilder().withValue('dev').build()).build()).build())
+    .withComponent(vpc).withComponent(subnet).withComponent(sg).withComponent(web).withComponent(api)
+    .build();
+}
 ```
-Important notes:
-
-* This code defines and deploys a Blueprint, not a Live System
-* Deployment registers the Blueprint with Fractal Cloud
-* No cloud resources are provisioned at this stage
-
-The following code instead, uses the same Blueprint to deploy a Live System to a specified Fractal Cloud Environment.
-
-```js
-// The Live System is defined using the Builder pattern
-const liveSystem = LiveSystem.getBuilder()
-  .withId(LiveSystem.Id.getBuilder()
-    .withBoundedContextId(bcId)
-    .withName(KebabCaseString.getBuilder().withValue("live-system-from-ts").build())
-    .build())
-  .withComponent(LiveSystem.Component.getBuilder()
-    .withId(fractal.components[0].id)
-    .withDescription(fractal.components[0].description)
-    .withType(fractal.components[0].type)
-    .withDisplayName(fractal.components[0].displayName)
-    .withVersion(fractal.components[0].version)
-    .build())
-  .withDescription('Live System deployed from TypeScript')
-  .withFractalId(fractal.id)
-  .withGenericProvider('Azure')
-  .withEnvironment(Environment.getBuilder()
-    .withId(Environment.Id.getBuilder()
-      .withOwnerType(OwnerType.Personal)
-      .withOwnerId(OwnerId.getBuilder().withValue('00000000-0000-0000-0000-000000000000').build())
-      .withName(KebabCaseString.getBuilder().withValue('test').build())
-      .build())
-    .build())
+
+### 3. Deploy (`index.ts`)
+
+```typescript
+import {ServiceAccountCredentials, ServiceAccountId} from '@fractal_cloud/sdk';
+import {fractal} from './fractal';
+import {getLiveSystem} from './aws_live_system';
+
+const credentials = ServiceAccountCredentials.getBuilder()
+  .withId(ServiceAccountId.getBuilder().withValue(process.env['SERVICE_ACCOUNT_ID']!).build())
+  .withSecret(process.env['SERVICE_ACCOUNT_SECRET']!)
   .build();
 
-// Deployment is initiated using the deploy method on the Live System object
-await liveSystem.deploy(serviceAccountCredentials);
+await fractal.deploy(credentials);
+await getLiveSystem().deploy(credentials);
 ```
 
-## Current limitations
+The blueprint is registered with Fractal Cloud. The Automation Engine reconciles cloud resources to match the Live System definition.
 
-This version intentionally exposes the raw model.
+## Deployment modes
 
-Known limitations include:
+`liveSystem.deploy()` supports two modes via an optional `DeployOptions` argument.
 
-1. No typed helpers for component types
-2. No Bounded Context or Environment abstractions
-3. API surface still evolving
+### Fire and forget (default)
 
-These limitations are addressed in the roadmap below.
+Submits the live system to Fractal Cloud and returns immediately. Provisioning happens asynchronously. Errors are logged but not thrown. This is the default when no options are passed.
 
-## Roadmap
+```typescript
+// Equivalent — both are fire-and-forget
+await liveSystem.deploy(credentials);
+await liveSystem.deploy(credentials, {mode: 'fire-and-forget'});
+```
 
-Planned development priorities are:
+Best for: **applications, CLIs, scripts** where infrastructure deployment is a background concern.
 
-1. Syntax sugar and typed helpers
-2. Bounded Context support
-3. Environment support
+### Wait for Active
 
-The API is expected to evolve as these capabilities are introduced. Feedback from early users will directly influence design decisions.
+Submits the live system, then polls until all components reach `Active` status. Throws if deployment fails (`FailedMutation`, `Error`) or if the timeout is exceeded.
 
-## Samples and learning resources
+```typescript
+await liveSystem.deploy(credentials, {
+  mode: 'wait',
+  pollIntervalMs: 10_000, // check every 10 s  (default: 5 s)
+  timeoutMs: 900_000,     // give up after 15 min (default: 10 min)
+});
+// reaches here only when the live system is fully Active
+```
 
-[Sample repository](https://github.com/Fractal-Cloud/fractal-ts-sdk-samples)
+Best for: **CI/CD pipelines** where the pipeline must not advance until infrastructure is fully provisioned.
 
-[Fractal Architecture documentation](https://docs.fractal.cloud/)
+---
 
-## Contributing and feedback
+## Multi-provider support
 
-Contributions and feedback are welcome.
+The same blueprint can be deployed on any supported provider. Live system files are short and only contain vendor-specific parameters — all structural decisions (dependencies, traffic rules, security rules) stay in the blueprint.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines
+| Blueprint component | AWS | Azure | GCP | OCI | Hetzner |
+|---------------------|-----|-------|-----|-----|---------|
+| `VirtualNetwork` | `AwsVpc` | `AzureVnet` | `GcpVpc` | `OciVcn` | `HetznerNetwork` |
+| `Subnet` | `AwsSubnet` | `AzureSubnet` | `GcpSubnet` | `OciSubnet` | `HetznerSubnet` |
+| `SecurityGroup` | `AwsSecurityGroup` | `AzureNsg` | `GcpFirewall` | `OciSecurityList` | `HetznerFirewall` |
+| `VirtualMachine` | `Ec2Instance` | `AzureVm` | `GcpVm` | `OciInstance` | `HetznerServer` |
 
-Use GitHub Issues for bugs and feature requests
+PaaS and CaaS helpers are also available for AWS ECS (cluster, task definition, service) and the agnostic `ContainerPlatform` / `Workload` blueprint types.
 
-Use GitHub Discussions for design and architectural questions
+## Samples
 
-Direct contact and Slack channels are available for early adopters
+The [sample repository](https://github.com/Fractal-Cloud/fractal-ts-sdk-samples) contains ready-to-run examples:
 
-This SDK is being built in close collaboration with its users.
+| Sample | Description |
+|--------|-------------|
+| `basic_iaas` | VPC + Subnet + Security Group + two VMs — deploys on AWS, Azure, GCP, OCI, or Hetzner via `CLOUD_PROVIDER` env var |
+| `basic_container_platform` | ECS Fargate — VPC + Subnet + Security Group + ECS Cluster + two workloads |
 
-## License
+## Architecture
+
+```
+src/
+  fractal/           # Cloud-agnostic blueprint helpers
+    component/
+      network_and_compute/iaas/   # VirtualNetwork, Subnet, SecurityGroup, VirtualMachine
+      network_and_compute/paas/   # ContainerPlatform
+      custom_workloads/caas/      # Workload
+  live_system/       # Provider-specific helpers
+    component/
+      network_and_compute/iaas/   # AWS, Azure, GCP, OCI, Hetzner components
+      network_and_compute/paas/   # AwsEcsCluster, AwsEcsTaskDefinition, AwsEcsService
+```
+
+## Contributing and feedback
+
+Contributions and feedback are welcome.
 
-This project is licensed under GPLv3.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines. Use GitHub Issues for bugs and feature requests, and GitHub Discussions for design questions.
+
+## License
 
-See the [LICENSE](LICENSE) file for details.
+Licensed under GPLv3. See the [LICENSE](LICENSE) file for details.
 
 Made with ❤️ by the Fractal Cloud team.