@fractal_cloud/sdk 0.1.2 → 1.0.0

package/README.md

@@ -9,10 +9,10 @@
 
 ## Overview
 
-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.
+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 0.1.0. It supports Blueprint definition and deployment and is intended for early production pilots and platform experimentation.
+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
 
@@ -44,12 +44,18 @@ You do not need prior knowledge of Fractal to use this SDK, the most important c
 
 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.
 
-### Blueprint
+#### Blueprint
 
 A Blueprint is the static definition of a Fractal.
 It describes components, their relationships, and their architectural intent.
 
+#### Interface
+
+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.
+
 ### Live System
 
 A Live System is a running instance of a Fractal deployed to a cloud environment.
@@ -59,22 +65,20 @@ For a deeper explanation of Fractal Architecture, see the documentation linked b
 
 ## What this SDK does today
 
-Version 0.1.0 supports the following capabilities.
+Version 1.0.0 supports the following capabilities.
 
-* Definition of Fractal Blueprints using TypeScript
+* 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:
 
-* Live System creation
-* Component instantiation
-* Lifecycle or operational actions
+* Fractal Interface definition
 * Bounded Context helpers
 * Environment helpers
 
-If you are looking to model architecture, validate concepts, or start early production pilots with Fractal Blueprints, this SDK is ready.
-
 ## Architectural positioning
 
 The Fractal TypeScript SDK acts as a bridge between software architecture and infrastructure automation.
@@ -111,15 +115,25 @@ The following example defines and deploys the smallest useful Fractal Blueprint
 It creates a Fractal with a single component and deploys the Blueprint to Fractal Cloud.
 
 ```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())
+  .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(BoundedContext.Id.getBuilder()
-      .withOwnerType(OwnerType.Personal)
-      .withOwnerId(OwnerId.getBuilder()
-        .withValue("1896f44c-9ff6-4dde-9a6d-f8d621d6bcab")
-        .build())
-      .withName(KebabCaseString.getBuilder().withValue("test-ang").build())
-      .build())
+    .withBoundedContextId(bcId)
     .withName(KebabCaseString.getBuilder().withValue("fractal-from-ts").build())
     .withVersion(Version.getBuilder().withMajor(1).withMinor(0).withPatch(0).build())
     .build())
@@ -138,13 +152,8 @@ const fractal = Fractal.getBuilder()
     .build())
   .build();
 
-await fractal.deploy(
-  ServiceAccountCredentials.getBuilder()
-    .withId(ServiceAccountId.getBuilder()
-      .withValue(process.env["SERVICE_ACCOUNT_ID"])
-    .build())
-  .withSecret(process.env["SERVICE_ACCOUNT_SECRET"])
-  .build());
+// Blueprint deployment is initiated using the deploy method on the Fractal object
+await fractal.deploy(serviceAccountCredentials);
 ```
 Important notes:
 
@@ -152,6 +161,38 @@ Important notes:
 * 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())
+  .build();
+
+// Deployment is initiated using the deploy method on the Live System object
+await liveSystem.deploy(serviceAccountCredentials);
+```
+
 ## Current limitations
 
 This version intentionally exposes the raw model.
@@ -168,10 +209,9 @@ These limitations are addressed in the roadmap below.
 
 Planned development priorities are:
 
-1. Live System support
-2. Syntax sugar and typed helpers
-3. Bounded Context support
-4. Environment support
+1. Syntax sugar and typed helpers
+2. Bounded Context support
+3. Environment support
 
 The API is expected to evolve as these capabilities are introduced. Feedback from early users will directly influence design decisions.