@fractal_cloud/sdk 0.1.2 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +168 -144
  2. package/dist/index.cjs +3336 -75
  3. package/dist/index.d.cts +1665 -13
  4. package/dist/index.d.mts +1665 -13
  5. package/dist/index.mjs +3160 -75
  6. package/package.json +15 -3
package/README.md CHANGED
@@ -2,204 +2,228 @@
2
2
 
3
3
  [![NPM Version][npm-image]][npm-url]
4
4
  [![build status][build-image]][build-url]
5
+ [![codecov][codecov-image]][codecov-url]
5
6
  [![license][license-image]](LICENSE)
6
7
  [![Known Vulnerabilities][snyk-image]][snyk-url]
7
- [![codecov][codecov-image]][codecov-url]
8
8
  [![TypeScript Style Guide][gts-image]][gts-url]
9
9
 
10
10
  ## Overview
11
11
 
12
- The Fractal TypeScript SDK is an early stage but production oriented SDK that allows platform engineers and application developers to define cloud agnostic infrastructure blueprints using TypeScript.
13
- 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.
14
- 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.
15
- This SDK is currently at version 0.1.0. It supports Blueprint definition and deployment and is intended for early production pilots and platform experimentation.
16
-
17
- ## Why Fractal
18
-
19
- Modern infrastructure automation forces teams to choose between flexibility and control.
20
-
21
- Traditional Infrastructure as Code approaches are:
22
-
23
- 1. Tightly coupled to a specific cloud vendor
24
- 2. Based on string heavy DSLs
25
- 3. Difficult to govern at scale
26
- 4. Focused on resources rather than architecture
27
-
28
- Fractal Cloud takes a different approach.
29
-
30
- Fractal Cloud allows you to:
12
+ 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.
31
13
 
32
- 1. Define infrastructure as architecture, not scripts
33
- 2. Use TypeScript instead of a DSL
34
- 3. Encode governance and intent directly into reusable blueprints
35
- 4. Remain cloud-agnostic by design
14
+ 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.
36
15
 
37
- This SDK is the programmatic interface to that model.
16
+ ## Why Fractal
38
17
 
39
- ## Core concepts in one minute
18
+ Traditional Infrastructure as Code forces a choice between flexibility and control:
40
19
 
41
- You do not need prior knowledge of Fractal to use this SDK, the most important concepts are explained below.
20
+ - Tightly coupled to a specific cloud vendor
21
+ - String-heavy DSLs with no type safety
22
+ - Hard to govern at scale
23
+ - Focused on raw resources rather than architecture
42
24
 
43
- ### Fractal
25
+ 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.
44
26
 
45
- A Fractal is a governed, reusable infrastructure construct.
46
- It defines what an infrastructure system is allowed to be, not just what it deploys.
27
+ ## Core concepts
47
28
 
48
- ### Blueprint
29
+ ### Fractal (Blueprint)
49
30
 
50
- A Blueprint is the static definition of a Fractal.
51
- It describes components, their relationships, and their architectural intent.
31
+ 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.
52
32
 
53
33
  ### Live System
54
34
 
55
- A Live System is a running instance of a Fractal deployed to a cloud environment.
56
- Live Systems are not yet supported in the TypeScript SDK.
57
-
58
- For a deeper explanation of Fractal Architecture, see the documentation linked below.
35
+ 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.
59
36
 
60
- ## What this SDK does today
37
+ ## What this SDK supports
61
38
 
62
- Version 0.1.0 supports the following capabilities.
39
+ - Definition of Fractal Blueprints using cloud-agnostic component helpers
40
+ - Deployment of Blueprints to Fractal Cloud
41
+ - Definition of Live Systems with typed, provider-specific helpers
42
+ - Deployment of Live Systems to any Fractal Cloud Environment
43
+ - Personal and organisation-owned accounts
44
+ - **IaaS helpers** for AWS, Azure, GCP, OCI, and Hetzner
45
+ - **PaaS helpers** for AWS ECS (cluster, task definition, service)
63
46
 
64
- * Definition of Fractal Blueprints using TypeScript
65
- * Deployment of Blueprints to Fractal Cloud
66
- * Usage from both personal and organization owned accounts
47
+ ## Installation
67
48
 
68
- This SDK does not yet support:
49
+ ```bash
50
+ npm install @fractal_cloud/sdk
51
+ ```
69
52
 
70
- * Live System creation
71
- * Component instantiation
72
- * Lifecycle or operational actions
73
- * Bounded Context helpers
74
- * Environment helpers
53
+ [Package page](https://www.npmjs.com/package/@fractal_cloud/sdk) · [Source repository](https://github.com/Fractal-Cloud/fractal-ts-sdk)
75
54
 
76
- If you are looking to model architecture, validate concepts, or start early production pilots with Fractal Blueprints, this SDK is ready.
55
+ Requires Node.js 18+ and TypeScript 5+.
77
56
 
78
- ## Architectural positioning
57
+ ## Quick start
79
58
 
80
- The Fractal TypeScript SDK acts as a bridge between software architecture and infrastructure automation.
59
+ The following example defines a cloud-agnostic blueprint with a VPC, a subnet, a security group, and two VMs — then deploys it on AWS.
81
60
 
82
- It allows teams to:
61
+ ### 1. Define the blueprint (`fractal.ts`)
83
62
 
84
- * Describe infrastructure using architectural concepts
85
- * Keep infrastructure definitions vendor neutral
86
- * Rely on the Fractal Automation Engine to interpret and enforce those definitions
63
+ ```typescript
64
+ import {
65
+ BoundedContext, Fractal, KebabCaseString, OwnerId, OwnerType, Version,
66
+ VirtualNetwork, Subnet, SecurityGroup, VirtualMachine,
67
+ } from '@fractal_cloud/sdk';
87
68
 
88
- This SDK does not replace cloud providers, nor does it expose raw infrastructure primitives.
89
- Instead, it defines intent and delegates execution to the Fractal Automation Engine.
69
+ const bcId = BoundedContext.Id.getBuilder()
70
+ .withOwnerType(OwnerType.Personal)
71
+ .withOwnerId(OwnerId.getBuilder().withValue(process.env['OWNER_ID']!).build())
72
+ .withName(KebabCaseString.getBuilder().withValue('my-team').build())
73
+ .build();
90
74
 
91
- This is Infrastructure as Code without cloud-specific code.
75
+ const apiServer = VirtualMachine.create({
76
+ id: 'api-server',
77
+ version: {major: 1, minor: 0, patch: 0},
78
+ displayName: 'API Server',
79
+ });
80
+
81
+ const webServer = VirtualMachine.create({
82
+ id: 'web-server',
83
+ version: {major: 1, minor: 0, patch: 0},
84
+ displayName: 'Web Server',
85
+ }).withLinks([{target: apiServer, fromPort: 8080}]);
86
+
87
+ const network = VirtualNetwork.create({
88
+ id: 'main-network',
89
+ version: {major: 1, minor: 0, patch: 0},
90
+ displayName: 'Main VPC',
91
+ cidrBlock: '10.0.0.0/16',
92
+ })
93
+ .withSubnets([
94
+ Subnet.create({
95
+ id: 'public-subnet',
96
+ version: {major: 1, minor: 0, patch: 0},
97
+ displayName: 'Public Subnet',
98
+ cidrBlock: '10.0.1.0/24',
99
+ }).withVirtualMachines([webServer, apiServer]),
100
+ ])
101
+ .withSecurityGroups([
102
+ SecurityGroup.create({
103
+ id: 'web-sg',
104
+ version: {major: 1, minor: 0, patch: 0},
105
+ displayName: 'Web Security Group',
106
+ description: 'Allow SSH and HTTP',
107
+ ingressRules: [
108
+ {protocol: 'tcp', fromPort: 22, toPort: 22, sourceCidr: '0.0.0.0/0'},
109
+ {protocol: 'tcp', fromPort: 80, toPort: 80, sourceCidr: '0.0.0.0/0'},
110
+ ],
111
+ }),
112
+ ]);
113
+
114
+ export const fractal = Fractal.getBuilder()
115
+ .withId(
116
+ Fractal.Id.getBuilder()
117
+ .withBoundedContextId(bcId)
118
+ .withName(KebabCaseString.getBuilder().withValue('my-iaas-fractal').build())
119
+ .withVersion(Version.getBuilder().withMajor(1).withMinor(0).withPatch(0).build())
120
+ .build(),
121
+ )
122
+ .withComponents([...network.components])
123
+ .build();
124
+ ```
92
125
 
93
- ## Installation
126
+ ### 2. Satisfy with AWS components (`aws_live_system.ts`)
127
+
128
+ ```typescript
129
+ import {
130
+ AwsVpc, AwsSubnet, AwsSecurityGroup, Ec2Instance,
131
+ Environment, KebabCaseString, LiveSystem, OwnerId, OwnerType,
132
+ } from '@fractal_cloud/sdk';
133
+ import {bcId, fractal} from './fractal';
134
+
135
+ function bp(id: string) {
136
+ const c = fractal.components.find(x => x.id.toString() === id);
137
+ if (!c) throw new Error(`Blueprint component '${id}' not found`);
138
+ return c;
139
+ }
140
+
141
+ export function getLiveSystem(): LiveSystem {
142
+ const vpc = AwsVpc.satisfy(bp('main-network')).withEnableDnsSupport(true).build();
143
+ const subnet = AwsSubnet.satisfy(bp('public-subnet')).withAvailabilityZone('eu-central-1a').build();
144
+ const sg = AwsSecurityGroup.satisfy(bp('web-sg')).build();
145
+ const web = Ec2Instance.satisfy(bp('web-server')).withAmiId('ami-0c55b159cbfafe1f0').withInstanceType('t3.micro').build();
146
+ const api = Ec2Instance.satisfy(bp('api-server')).withAmiId('ami-0c55b159cbfafe1f0').withInstanceType('t3.small').build();
147
+
148
+ return LiveSystem.getBuilder()
149
+ .withId(LiveSystem.Id.getBuilder().withBoundedContextId(bcId)
150
+ .withName(KebabCaseString.getBuilder().withValue('my-iaas-aws').build()).build())
151
+ .withFractalId(fractal.id)
152
+ .withGenericProvider('AWS')
153
+ .withEnvironment(Environment.getBuilder()
154
+ .withId(Environment.Id.getBuilder()
155
+ .withOwnerType(OwnerType.Personal)
156
+ .withOwnerId(OwnerId.getBuilder().withValue(process.env['OWNER_ID']!).build())
157
+ .withName(KebabCaseString.getBuilder().withValue('dev').build()).build()).build())
158
+ .withComponent(vpc).withComponent(subnet).withComponent(sg).withComponent(web).withComponent(api)
159
+ .build();
160
+ }
161
+ ```
94
162
 
95
- The SDK is published as a public npm package.
163
+ ### 3. Deploy (`index.ts`)
96
164
 
97
- ```bash
98
- npm install @fractal_cloud/sdk
99
- ```
165
+ ```typescript
166
+ import {ServiceAccountCredentials, ServiceAccountId} from '@fractal_cloud/sdk';
167
+ import {fractal} from './fractal';
168
+ import {getLiveSystem} from './aws_live_system';
100
169
 
101
- [Package page](https://www.npmjs.com/package/@fractal_cloud/sdk)
102
-
103
- [Source repository](https://github.com/Fractal-Cloud/fractal-ts-sdk)
104
-
105
- Node.js and TypeScript requirements are documented in the repository and follow standard modern LTS versions.
106
-
107
- ## Minimal example
108
-
109
- The following example defines and deploys the smallest useful Fractal Blueprint supported today.
110
-
111
- It creates a Fractal with a single component and deploys the Blueprint to Fractal Cloud.
112
-
113
- ```js
114
- const fractal = Fractal.getBuilder()
115
- .withId(Fractal.Id.getBuilder()
116
- .withBoundedContextId(BoundedContext.Id.getBuilder()
117
- .withOwnerType(OwnerType.Personal)
118
- .withOwnerId(OwnerId.getBuilder()
119
- .withValue("1896f44c-9ff6-4dde-9a6d-f8d621d6bcab")
120
- .build())
121
- .withName(KebabCaseString.getBuilder().withValue("test-ang").build())
122
- .build())
123
- .withName(KebabCaseString.getBuilder().withValue("fractal-from-ts").build())
124
- .withVersion(Version.getBuilder().withMajor(1).withMinor(0).withPatch(0).build())
125
- .build())
126
- .withComponent(Fractal.Component.getBuilder()
127
- .withId(Fractal.Component.Id.getBuilder()
128
- .withValue(KebabCaseString.getBuilder().withValue("container-orchestrator").build())
129
- .build())
130
- .withVersion(Version.getBuilder().withMajor(1).withMinor(0).withPatch(0).build())
131
- .withDescription("Container orchestrator for the fractal")
132
- .withDisplayName("Container orchestrator")
133
- .withType(Fractal.Component.Type.getBuilder()
134
- .withInfrastructureDomain(InfrastructureDomain.NetworkAndCompute)
135
- .withServiceDeliveryModel(ServiceDeliveryModel.PaaS)
136
- .withName(PascalCaseString.getBuilder().withValue("Kubernetes").build())
137
- .build())
138
- .build())
170
+ const credentials = ServiceAccountCredentials.getBuilder()
171
+ .withId(ServiceAccountId.getBuilder().withValue(process.env['SERVICE_ACCOUNT_ID']!).build())
172
+ .withSecret(process.env['SERVICE_ACCOUNT_SECRET']!)
139
173
  .build();
140
174
 
141
- await fractal.deploy(
142
- ServiceAccountCredentials.getBuilder()
143
- .withId(ServiceAccountId.getBuilder()
144
- .withValue(process.env["SERVICE_ACCOUNT_ID"])
145
- .build())
146
- .withSecret(process.env["SERVICE_ACCOUNT_SECRET"])
147
- .build());
175
+ await fractal.deploy(credentials);
176
+ await getLiveSystem().deploy(credentials);
148
177
  ```
149
- Important notes:
150
-
151
- * This code defines and deploys a Blueprint, not a Live System
152
- * Deployment registers the Blueprint with Fractal Cloud
153
- * No cloud resources are provisioned at this stage
154
-
155
- ## Current limitations
156
178
 
157
- This version intentionally exposes the raw model.
179
+ The blueprint is registered with Fractal Cloud. The Automation Engine reconciles cloud resources to match the Live System definition.
158
180
 
159
- Known limitations include:
181
+ ## Multi-provider support
160
182
 
161
- 1. No typed helpers for component types
162
- 2. No Bounded Context or Environment abstractions
163
- 3. API surface still evolving
183
+ 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.
164
184
 
165
- These limitations are addressed in the roadmap below.
185
+ | Blueprint component | AWS | Azure | GCP | OCI | Hetzner |
186
+ |---------------------|-----|-------|-----|-----|---------|
187
+ | `VirtualNetwork` | `AwsVpc` | `AzureVnet` | `GcpVpc` | `OciVcn` | `HetznerNetwork` |
188
+ | `Subnet` | `AwsSubnet` | `AzureSubnet` | `GcpSubnet` | `OciSubnet` | `HetznerSubnet` |
189
+ | `SecurityGroup` | `AwsSecurityGroup` | `AzureNsg` | `GcpFirewall` | `OciSecurityList` | `HetznerFirewall` |
190
+ | `VirtualMachine` | `Ec2Instance` | `AzureVm` | `GcpVm` | `OciInstance` | `HetznerServer` |
166
191
 
167
- ## Roadmap
192
+ PaaS and CaaS helpers are also available for AWS ECS (cluster, task definition, service) and the agnostic `ContainerPlatform` / `Workload` blueprint types.
168
193
 
169
- Planned development priorities are:
194
+ ## Samples
170
195
 
171
- 1. Live System support
172
- 2. Syntax sugar and typed helpers
173
- 3. Bounded Context support
174
- 4. Environment support
196
+ The [sample repository](https://github.com/Fractal-Cloud/fractal-ts-sdk-samples) contains ready-to-run examples:
175
197
 
176
- The API is expected to evolve as these capabilities are introduced. Feedback from early users will directly influence design decisions.
198
+ | Sample | Description |
199
+ |--------|-------------|
200
+ | `basic_iaas` | VPC + Subnet + Security Group + two VMs — deploys on AWS, Azure, GCP, OCI, or Hetzner via `CLOUD_PROVIDER` env var |
201
+ | `basic_container_platform` | ECS Fargate — VPC + Subnet + Security Group + ECS Cluster + two workloads |
177
202
 
178
- ## Samples and learning resources
203
+ ## Architecture
179
204
 
180
- [Sample repository](https://github.com/Fractal-Cloud/fractal-ts-sdk-samples)
181
-
182
- [Fractal Architecture documentation](https://docs.fractal.cloud/)
205
+ ```
206
+ src/
207
+ fractal/ # Cloud-agnostic blueprint helpers
208
+ component/
209
+ network_and_compute/iaas/ # VirtualNetwork, Subnet, SecurityGroup, VirtualMachine
210
+ network_and_compute/paas/ # ContainerPlatform
211
+ custom_workloads/caas/ # Workload
212
+ live_system/ # Provider-specific helpers
213
+ component/
214
+ network_and_compute/iaas/ # AWS, Azure, GCP, OCI, Hetzner components
215
+ network_and_compute/paas/ # AwsEcsCluster, AwsEcsTaskDefinition, AwsEcsService
216
+ ```
183
217
 
184
218
  ## Contributing and feedback
185
219
 
186
220
  Contributions and feedback are welcome.
187
221
 
188
- See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines
189
-
190
- Use GitHub Issues for bugs and feature requests
191
-
192
- Use GitHub Discussions for design and architectural questions
193
-
194
- Direct contact and Slack channels are available for early adopters
195
-
196
- This SDK is being built in close collaboration with its users.
222
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines. Use GitHub Issues for bugs and feature requests, and GitHub Discussions for design questions.
197
223
 
198
224
  ## License
199
225
 
200
- This project is licensed under GPLv3.
201
-
202
- See the [LICENSE](LICENSE) file for details.
226
+ Licensed under GPLv3. See the [LICENSE](LICENSE) file for details.
203
227
 
204
228
  Made with ❤️ by the Fractal Cloud team.
205
229