@fractal_cloud/sdk 1.0.0 → 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 +162 -178
  2. package/dist/index.cjs +2689 -5
  3. package/dist/index.d.cts +1204 -1
  4. package/dist/index.d.mts +1204 -1
  5. package/dist/index.mjs +2515 -5
  6. package/package.json +15 -3
package/README.md CHANGED
@@ -2,244 +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 ready 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 1.0.0. It supports Blueprint and Live System 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.
38
-
39
- ## Core concepts in one minute
40
-
41
- You do not need prior knowledge of Fractal to use this SDK, the most important concepts are explained below.
16
+ ## Why Fractal
42
17
 
43
- ### Fractal
18
+ Traditional Infrastructure as Code forces a choice between flexibility and control:
44
19
 
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.
47
- It is composed by a Blueprint and an Interface.
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
48
24
 
49
- #### Blueprint
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.
50
26
 
51
- A Blueprint is the static definition of a Fractal.
52
- It describes components, their relationships, and their architectural intent.
27
+ ## Core concepts
53
28
 
54
- #### Interface
29
+ ### Fractal (Blueprint)
55
30
 
56
- An Interface is the versioned set of operations through which a Fractal can be specialized or extended.
57
- These operations may involve the addition, removal, or modification of components and their integrations within the Fractal.
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.
58
32
 
59
33
  ### Live System
60
34
 
61
- A Live System is a running instance of a Fractal deployed to a cloud environment.
62
- Live Systems are not yet supported in the TypeScript SDK.
63
-
64
- For a deeper explanation of Fractal Architecture, see the documentation linked below.
65
-
66
- ## What this SDK does today
67
-
68
- Version 1.0.0 supports the following capabilities.
69
-
70
- * Definition of Fractal Blueprints
71
- * Deployment of Blueprints to Fractal Cloud
72
- * Definition of Live Systems
73
- * Deployment of Live Systems to a specified Fractal Cloud Environment
74
- * Usage from both personal and organization owned accounts
75
-
76
- This SDK does not yet support:
77
-
78
- * Fractal Interface definition
79
- * Bounded Context helpers
80
- * Environment helpers
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.
81
36
 
82
- ## Architectural positioning
37
+ ## What this SDK supports
83
38
 
84
- The Fractal TypeScript SDK acts as a bridge between software architecture and infrastructure automation.
85
-
86
- It allows teams to:
87
-
88
- * Describe infrastructure using architectural concepts
89
- * Keep infrastructure definitions vendor neutral
90
- * Rely on the Fractal Automation Engine to interpret and enforce those definitions
91
-
92
- This SDK does not replace cloud providers, nor does it expose raw infrastructure primitives.
93
- Instead, it defines intent and delegates execution to the Fractal Automation Engine.
94
-
95
- This is Infrastructure as Code without cloud-specific code.
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)
96
46
 
97
47
  ## Installation
98
48
 
99
- The SDK is published as a public npm package.
100
-
101
49
  ```bash
102
50
  npm install @fractal_cloud/sdk
103
51
  ```
104
52
 
105
- [Package page](https://www.npmjs.com/package/@fractal_cloud/sdk)
53
+ [Package page](https://www.npmjs.com/package/@fractal_cloud/sdk) · [Source repository](https://github.com/Fractal-Cloud/fractal-ts-sdk)
106
54
 
107
- [Source repository](https://github.com/Fractal-Cloud/fractal-ts-sdk)
55
+ Requires Node.js 18+ and TypeScript 5+.
108
56
 
109
- Node.js and TypeScript requirements are documented in the repository and follow standard modern LTS versions.
57
+ ## Quick start
110
58
 
111
- ## Minimal example
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.
112
60
 
113
- The following example defines and deploys the smallest useful Fractal Blueprint supported today.
61
+ ### 1. Define the blueprint (`fractal.ts`)
114
62
 
115
- It creates a Fractal with a single component and deploys the Blueprint to Fractal Cloud.
63
+ ```typescript
64
+ import {
65
+ BoundedContext, Fractal, KebabCaseString, OwnerId, OwnerType, Version,
66
+ VirtualNetwork, Subnet, SecurityGroup, VirtualMachine,
67
+ } from '@fractal_cloud/sdk';
116
68
 
117
- ```js
118
- // The Bounded Context ID is used to group Blueprints and Live System in order to granularly control access within an Organization
119
69
  const bcId = BoundedContext.Id.getBuilder()
120
70
  .withOwnerType(OwnerType.Personal)
121
- .withOwnerId(OwnerId.getBuilder()
122
- .withValue("00000000-0000-0000-0000-000000000000")
123
- .build())
124
- .withName(KebabCaseString.getBuilder().withValue("test").build())
71
+ .withOwnerId(OwnerId.getBuilder().withValue(process.env['OWNER_ID']!).build())
72
+ .withName(KebabCaseString.getBuilder().withValue('my-team').build())
125
73
  .build();
126
74
 
127
- // Service account credentials are obtained from environment variables
128
- const serviceAccountCredentials = ServiceAccountCredentials.getBuilder()
129
- .withId(ServiceAccountId.getBuilder().withValue(process.env['SERVICE_ACCOUNT_ID']).build())
130
- .withSecret(process.env['SERVICE_ACCOUNT_SECRET'])
131
- .build();
132
-
133
- // The Fractal is defined using the Builder pattern
134
- const fractal = Fractal.getBuilder()
135
- .withId(Fractal.Id.getBuilder()
136
- .withBoundedContextId(bcId)
137
- .withName(KebabCaseString.getBuilder().withValue("fractal-from-ts").build())
138
- .withVersion(Version.getBuilder().withMajor(1).withMinor(0).withPatch(0).build())
139
- .build())
140
- .withComponent(Fractal.Component.getBuilder()
141
- .withId(Fractal.Component.Id.getBuilder()
142
- .withValue(KebabCaseString.getBuilder().withValue("container-orchestrator").build())
143
- .build())
144
- .withVersion(Version.getBuilder().withMajor(1).withMinor(0).withPatch(0).build())
145
- .withDescription("Container orchestrator for the fractal")
146
- .withDisplayName("Container orchestrator")
147
- .withType(Fractal.Component.Type.getBuilder()
148
- .withInfrastructureDomain(InfrastructureDomain.NetworkAndCompute)
149
- .withServiceDeliveryModel(ServiceDeliveryModel.PaaS)
150
- .withName(PascalCaseString.getBuilder().withValue("Kubernetes").build())
151
- .build())
152
- .build())
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])
153
123
  .build();
154
-
155
- // Blueprint deployment is initiated using the deploy method on the Fractal object
156
- await fractal.deploy(serviceAccountCredentials);
157
124
  ```
158
- Important notes:
159
-
160
- * This code defines and deploys a Blueprint, not a Live System
161
- * Deployment registers the Blueprint with Fractal Cloud
162
- * No cloud resources are provisioned at this stage
163
-
164
- The following code instead, uses the same Blueprint to deploy a Live System to a specified Fractal Cloud Environment.
165
-
166
- ```js
167
- // The Live System is defined using the Builder pattern
168
- const liveSystem = LiveSystem.getBuilder()
169
- .withId(LiveSystem.Id.getBuilder()
170
- .withBoundedContextId(bcId)
171
- .withName(KebabCaseString.getBuilder().withValue("live-system-from-ts").build())
172
- .build())
173
- .withComponent(LiveSystem.Component.getBuilder()
174
- .withId(fractal.components[0].id)
175
- .withDescription(fractal.components[0].description)
176
- .withType(fractal.components[0].type)
177
- .withDisplayName(fractal.components[0].displayName)
178
- .withVersion(fractal.components[0].version)
179
- .build())
180
- .withDescription('Live System deployed from TypeScript')
181
- .withFractalId(fractal.id)
182
- .withGenericProvider('Azure')
183
- .withEnvironment(Environment.getBuilder()
184
- .withId(Environment.Id.getBuilder()
185
- .withOwnerType(OwnerType.Personal)
186
- .withOwnerId(OwnerId.getBuilder().withValue('00000000-0000-0000-0000-000000000000').build())
187
- .withName(KebabCaseString.getBuilder().withValue('test').build())
188
- .build())
189
- .build())
190
- .build();
191
125
 
192
- // Deployment is initiated using the deploy method on the Live System object
193
- await liveSystem.deploy(serviceAccountCredentials);
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
+ }
194
161
  ```
195
162
 
196
- ## Current limitations
197
-
198
- This version intentionally exposes the raw model.
199
-
200
- Known limitations include:
163
+ ### 3. Deploy (`index.ts`)
201
164
 
202
- 1. No typed helpers for component types
203
- 2. No Bounded Context or Environment abstractions
204
- 3. API surface still evolving
165
+ ```typescript
166
+ import {ServiceAccountCredentials, ServiceAccountId} from '@fractal_cloud/sdk';
167
+ import {fractal} from './fractal';
168
+ import {getLiveSystem} from './aws_live_system';
205
169
 
206
- These limitations are addressed in the roadmap below.
170
+ const credentials = ServiceAccountCredentials.getBuilder()
171
+ .withId(ServiceAccountId.getBuilder().withValue(process.env['SERVICE_ACCOUNT_ID']!).build())
172
+ .withSecret(process.env['SERVICE_ACCOUNT_SECRET']!)
173
+ .build();
207
174
 
208
- ## Roadmap
175
+ await fractal.deploy(credentials);
176
+ await getLiveSystem().deploy(credentials);
177
+ ```
209
178
 
210
- Planned development priorities are:
179
+ The blueprint is registered with Fractal Cloud. The Automation Engine reconciles cloud resources to match the Live System definition.
211
180
 
212
- 1. Syntax sugar and typed helpers
213
- 2. Bounded Context support
214
- 3. Environment support
181
+ ## Multi-provider support
215
182
 
216
- The API is expected to evolve as these capabilities are introduced. Feedback from early users will directly influence design decisions.
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.
217
184
 
218
- ## Samples and learning resources
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` |
219
191
 
220
- [Sample repository](https://github.com/Fractal-Cloud/fractal-ts-sdk-samples)
192
+ PaaS and CaaS helpers are also available for AWS ECS (cluster, task definition, service) and the agnostic `ContainerPlatform` / `Workload` blueprint types.
221
193
 
222
- [Fractal Architecture documentation](https://docs.fractal.cloud/)
194
+ ## Samples
223
195
 
224
- ## Contributing and feedback
196
+ The [sample repository](https://github.com/Fractal-Cloud/fractal-ts-sdk-samples) contains ready-to-run examples:
225
197
 
226
- Contributions and feedback are welcome.
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 |
227
202
 
228
- See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines
203
+ ## Architecture
229
204
 
230
- Use GitHub Issues for bugs and feature requests
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
+ ```
231
217
 
232
- Use GitHub Discussions for design and architectural questions
218
+ ## Contributing and feedback
233
219
 
234
- Direct contact and Slack channels are available for early adopters
220
+ Contributions and feedback are welcome.
235
221
 
236
- 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.
237
223
 
238
224
  ## License
239
225
 
240
- This project is licensed under GPLv3.
241
-
242
- See the [LICENSE](LICENSE) file for details.
226
+ Licensed under GPLv3. See the [LICENSE](LICENSE) file for details.
243
227
 
244
228
  Made with ❤️ by the Fractal Cloud team.
245
229