@shotstack/schemas 1.3.9 → 1.4.1

package/README.md

@@ -1,89 +1,89 @@
-# @shotstack/schemas
-
-Centralized OpenAPI schemas and TypeScript types for the Shotstack API.
-
-## Installation
-
-```bash
-npm install @shotstack/schemas zod
-```
-
-## Usage
-
-### TypeScript Types
-
-```typescript
-import type { components } from '@shotstack/schemas';
-
-type Edit = components['schemas']['Edit'];
-type Timeline = components['schemas']['Timeline'];
-type Clip = components['schemas']['Clip'];
-type Output = components['schemas']['Output'];
-```
-
-### Zod Schemas
-
-```typescript
-import { z } from 'zod';
-import { richTextAssetSchema, editSchema, timelineSchema } from '@shotstack/schemas/zod';
-
-const result = richTextAssetSchema.safeParse(inputData);
-if (result.success) {
-  console.log(result.data);
-}
-```
-
-### Extending Schemas
-
-```typescript
-import { z } from 'zod';
-import { richTextAssetSchema } from '@shotstack/schemas/zod';
-
-const ExtendedAsset = richTextAssetSchema.extend({
-  customFonts: z.array(z.object({
-    src: z.string().url(),
-    family: z.string(),
-  })).optional(),
-  border: z.object({
-    width: z.number().min(0),
-    color: z.string(),
-  }).optional(),
-});
-
-type ExtendedAssetType = z.infer<typeof ExtendedAsset>;
-```
-
-### Custom Validation
-
-```typescript
-import { richTextAnimationSchema } from '@shotstack/schemas/zod';
-
-const AnimationWithDirection = richTextAnimationSchema.refine(
-  (data) => {
-    if (data.preset === 'slideIn' && !data.direction) {
-      return false;
-    }
-    return true;
-  },
-  { message: 'direction is required for slideIn preset' }
-);
-```
-
-## Available Schemas
-
-- Edit, Timeline, Track, Clip, Output
-- Assets: VideoAsset, ImageAsset, AudioAsset, HtmlAsset, TextAsset, TitleAsset, LumaAsset, CaptionAsset, ShapeAsset, RichTextAsset
-- Destinations: ShotstackDestination, S3Destination, MuxDestination, VimeoDestination, GoogleDriveDestination, GoogleCloudStorageDestination
-- Transforms, Transitions, Fonts, MergeFields, and more
-
-## Development
-
-```bash
-pnpm install
-pnpm run build
-pnpm run test
-```
-
-## License
-
-MIT
+# @shotstack/schemas
+
+Centralized OpenAPI schemas and TypeScript types for the Shotstack API.
+
+## Installation
+
+```bash
+npm install @shotstack/schemas zod
+```
+
+## Usage
+
+### TypeScript Types
+
+```typescript
+import type { components } from '@shotstack/schemas';
+
+type Edit = components['schemas']['Edit'];
+type Timeline = components['schemas']['Timeline'];
+type Clip = components['schemas']['Clip'];
+type Output = components['schemas']['Output'];
+```
+
+### Zod Schemas
+
+```typescript
+import { z } from 'zod';
+import { richTextAssetSchema, editSchema, timelineSchema } from '@shotstack/schemas/zod';
+
+const result = richTextAssetSchema.safeParse(inputData);
+if (result.success) {
+  console.log(result.data);
+}
+```
+
+### Extending Schemas
+
+```typescript
+import { z } from 'zod';
+import { richTextAssetSchema } from '@shotstack/schemas/zod';
+
+const ExtendedAsset = richTextAssetSchema.extend({
+  customFonts: z.array(z.object({
+    src: z.string().url(),
+    family: z.string(),
+  })).optional(),
+  border: z.object({
+    width: z.number().min(0),
+    color: z.string(),
+  }).optional(),
+});
+
+type ExtendedAssetType = z.infer<typeof ExtendedAsset>;
+```
+
+### Custom Validation
+
+```typescript
+import { richTextAnimationSchema } from '@shotstack/schemas/zod';
+
+const AnimationWithDirection = richTextAnimationSchema.refine(
+  (data) => {
+    if (data.preset === 'slideIn' && !data.direction) {
+      return false;
+    }
+    return true;
+  },
+  { message: 'direction is required for slideIn preset' }
+);
+```
+
+## Available Schemas
+
+- Edit, Timeline, Track, Clip, Output
+- Assets: VideoAsset, ImageAsset, AudioAsset, HtmlAsset, TextAsset, TitleAsset, LumaAsset, CaptionAsset, ShapeAsset, RichTextAsset
+- Destinations: ShotstackDestination, S3Destination, MuxDestination, VimeoDestination, GoogleDriveDestination, GoogleCloudStorageDestination
+- Transforms, Transitions, Fonts, MergeFields, and more
+
+## Development
+
+```bash
+pnpm install
+pnpm run build
+pnpm run test
+```
+
+## License
+
+MIT

package/dist/api.bundled.json

@@ -2056,7 +2056,7 @@
         ]
       },
       "SvgAsset": {
-        "description": "The SvgAsset is used to add scalable vector graphics (SVG) shapes to a video.\nIt provides a comprehensive set of primitive shapes and custom paths with full\nstyling support including fills, strokes, gradients, and shadows.\n\n**Available Shapes:**\n- `rectangle` - Rectangles with optional rounded corners\n- `circle` - Perfect circles\n- `ellipse` - Ellipses/ovals with separate x and y radii\n- `line` - Straight lines with configurable thickness\n- `polygon` - Regular polygons (triangle, pentagon, hexagon, etc.)\n- `star` - Multi-pointed stars\n- `arrow` - Directional arrows\n- `heart` - Heart shapes\n- `cross` - Plus/cross shapes\n- `ring` - Donut/ring shapes\n- `path` - Custom shapes using SVG path data\n\n**Styling Options:**\n- Fill with solid colors or linear/radial gradients\n- Stroke with configurable width, color, dash patterns, and line caps/joins\n- Drop shadows with blur, offset, and opacity\n- Transform properties for positioning, rotation, and scaling\n\nSee [W3C SVG 2 Specification](https://www.w3.org/TR/SVG2/) for path data syntax.\n",
+        "description": "The SvgAsset is used to add scalable vector graphics (SVG) shapes to a video.\nIt provides two mutually exclusive ways to define shapes:\n\n**Option 1: Import SVG markup using `src`**\n```json\n{\n  \"type\": \"svg\",\n  \"src\": \"<svg width=\\\"100\\\" height=\\\"100\\\"><circle cx=\\\"50\\\" cy=\\\"50\\\" r=\\\"40\\\" fill=\\\"#FF0000\\\"/></svg>\"\n}\n```\nWhen using `src`, no other properties are allowed. The fill, stroke, and dimensions\nare automatically extracted from the SVG markup.\n\n**Option 2: Define shapes programmatically using `shape`**\n```json\n{\n  \"type\": \"svg\",\n  \"shape\": { \"type\": \"circle\", \"radius\": 50 },\n  \"fill\": { \"type\": \"solid\", \"color\": \"#FF0000\" }\n}\n```\nWhen using `shape`, you can customize fill, stroke, shadow, transform, and other properties.\nThe `src` property is not allowed in this mode.\n\n**Important:** You must provide either `src` OR `shape`, but not both.\nThese two modes are mutually exclusive.\n\n**Available Shapes (Option 2 only):**\n- `rectangle` - Rectangles with optional rounded corners\n- `circle` - Perfect circles\n- `ellipse` - Ellipses/ovals with separate x and y radii\n- `line` - Straight lines with configurable thickness\n- `polygon` - Regular polygons (triangle, pentagon, hexagon, etc.)\n- `star` - Multi-pointed stars\n- `arrow` - Directional arrows\n- `heart` - Heart shapes\n- `cross` - Plus/cross shapes\n- `ring` - Donut/ring shapes\n- `path` - Custom shapes using SVG path data\n\nSee [W3C SVG 2 Specification](https://www.w3.org/TR/SVG2/) for path data syntax.\n",
         "type": "object",
         "properties": {
           "type": {
@@ -2068,28 +2068,35 @@
             "default": "svg",
             "example": "svg"
           },
+          "src": {
+            "description": "Raw SVG markup string to import. When provided, the shape is extracted\nautomatically from the SVG content.\n\n**Supported elements:** `<path>`, `<rect>`, `<circle>`, `<ellipse>`,\n`<line>`, `<polygon>`, `<polyline>`\n\n**Automatically extracted:**\n- Path data (converted to a single combined path)\n- Fill color (from `fill` attribute or `style`)\n- Stroke color and width (from attributes or `style`)\n- Dimensions (from `width`/`height` or `viewBox`)\n- Opacity (from `opacity` attribute)\n\n**Important:** When using `src`, no other properties (shape, fill, stroke, etc.)\nare allowed. All styling must be defined within the SVG markup itself.\n",
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 500000,
+            "example": "<svg width=\"100\" height=\"100\"><circle cx=\"50\" cy=\"50\" r=\"40\" fill=\"#3498db\"/></svg>"
+          },
           "shape": {
-            "description": "The shape definition. The `type` property within determines the shape kind\nand its specific properties. See individual shape documentation for details.\n",
+            "description": "The shape definition using primitives. The `type` property within determines\nthe shape kind and its specific properties.\n\n**Important:** When using `shape`, the `src` property is not allowed.\n",
             "$ref": "#/components/schemas/SvgShape"
           },
           "fill": {
-            "description": "Fill properties for the shape interior.\nCan be a solid color or a gradient (linear/radial).\nIf omitted, the shape will have no fill (transparent interior).\n",
+            "description": "Fill properties for the shape interior.\nCan be a solid color or a gradient (linear/radial).\nIf omitted, the shape will have no fill (transparent interior).\n\n**Note:** Only allowed when using `shape`, not with `src`.\n",
             "$ref": "#/components/schemas/SvgFill"
           },
           "stroke": {
-            "description": "Stroke (outline) properties for the shape.\nIf omitted, the shape will have no stroke (no outline).\n",
+            "description": "Stroke (outline) properties for the shape.\nIf omitted, the shape will have no stroke (no outline).\n\n**Note:** Only allowed when using `shape`, not with `src`.\n",
             "$ref": "#/components/schemas/SvgStroke"
           },
           "shadow": {
-            "description": "Drop shadow properties for the shape.\nCreates a shadow effect behind the shape.\n",
+            "description": "Drop shadow properties for the shape.\nCreates a shadow effect behind the shape.\n\n**Note:** Only allowed when using `shape`, not with `src`.\n",
             "$ref": "#/components/schemas/SvgShadow"
           },
           "transform": {
-            "description": "Transform properties for positioning, rotating, and scaling the shape.\nThe transform is applied relative to the transformation origin.\n",
+            "description": "Transform properties for positioning, rotating, and scaling the shape.\nThe transform is applied relative to the transformation origin.\n\n**Note:** Only allowed when using `shape`, not with `src`.\n",
             "$ref": "#/components/schemas/SvgTransform"
           },
           "opacity": {
-            "description": "The overall opacity of the entire shape (including fill, stroke, and shadow).\n`1` is fully opaque, `0` is fully transparent.\nThis is applied on top of individual fill/stroke/shadow opacity values.\n",
+            "description": "The overall opacity of the entire shape (including fill, stroke, and shadow).\n`1` is fully opaque, `0` is fully transparent.\nThis is applied on top of individual fill/stroke/shadow opacity values.\n\n**Note:** Only allowed when using `shape`, not with `src`.\n",
             "type": "number",
             "minimum": 0,
             "maximum": 1,
@@ -2097,14 +2104,14 @@
             "example": 1
           },
           "width": {
-            "description": "The width of the bounding box in pixels.\nIf specified, the shape may be scaled to fit within this width.\nIf omitted, the shape uses its natural dimensions.\n",
+            "description": "The width of the bounding box in pixels.\nIf specified, the shape may be scaled to fit within this width.\nIf omitted, the shape uses its natural dimensions.\n\n**Note:** Only allowed when using `shape`, not with `src`.\n",
             "type": "integer",
             "minimum": 1,
             "maximum": 4096,
             "example": 400
           },
           "height": {
-            "description": "The height of the bounding box in pixels.\nIf specified, the shape may be scaled to fit within this height.\nIf omitted, the shape uses its natural dimensions.\n",
+            "description": "The height of the bounding box in pixels.\nIf specified, the shape may be scaled to fit within this height.\nIf omitted, the shape uses its natural dimensions.\n\n**Note:** Only allowed when using `shape`, not with `src`.\n",
             "type": "integer",
             "minimum": 1,
             "maximum": 4096,
@@ -2112,8 +2119,7 @@
           }
         },
         "required": [
-          "type",
-          "shape"
+          "type"
         ],
         "example": {
           "type": "svg",

package/dist/schema.d.ts

@@ -1149,10 +1149,33 @@ export interface components {
         };
         /**
          * @description The SvgAsset is used to add scalable vector graphics (SVG) shapes to a video.
-         *     It provides a comprehensive set of primitive shapes and custom paths with full
-         *     styling support including fills, strokes, gradients, and shadows.
+         *     It provides two mutually exclusive ways to define shapes:
          *
-         *     **Available Shapes:**
+         *     **Option 1: Import SVG markup using `src`**
+         *     ```json
+         *     {
+         *       "type": "svg",
+         *       "src": "<svg width=\"100\" height=\"100\"><circle cx=\"50\" cy=\"50\" r=\"40\" fill=\"#FF0000\"/></svg>"
+         *     }
+         *     ```
+         *     When using `src`, no other properties are allowed. The fill, stroke, and dimensions
+         *     are automatically extracted from the SVG markup.
+         *
+         *     **Option 2: Define shapes programmatically using `shape`**
+         *     ```json
+         *     {
+         *       "type": "svg",
+         *       "shape": { "type": "circle", "radius": 50 },
+         *       "fill": { "type": "solid", "color": "#FF0000" }
+         *     }
+         *     ```
+         *     When using `shape`, you can customize fill, stroke, shadow, transform, and other properties.
+         *     The `src` property is not allowed in this mode.
+         *
+         *     **Important:** You must provide either `src` OR `shape`, but not both.
+         *     These two modes are mutually exclusive.
+         *
+         *     **Available Shapes (Option 2 only):**
          *     - `rectangle` - Rectangles with optional rounded corners
          *     - `circle` - Perfect circles
          *     - `ellipse` - Ellipses/ovals with separate x and y radii
@@ -1165,12 +1188,6 @@ export interface components {
          *     - `ring` - Donut/ring shapes
          *     - `path` - Custom shapes using SVG path data
          *
-         *     **Styling Options:**
-         *     - Fill with solid colors or linear/radial gradients
-         *     - Stroke with configurable width, color, dash patterns, and line caps/joins
-         *     - Drop shadows with blur, offset, and opacity
-         *     - Transform properties for positioning, rotation, and scaling
-         *
          *     See [W3C SVG 2 Specification](https://www.w3.org/TR/SVG2/) for path data syntax.
          * @example {
          *       "type": "svg",
@@ -1218,35 +1235,66 @@ export interface components {
              */
             type: "svg";
             /**
-             * @description The shape definition. The `type` property within determines the shape kind
-             *     and its specific properties. See individual shape documentation for details.
+             * @description Raw SVG markup string to import. When provided, the shape is extracted
+             *     automatically from the SVG content.
+             *
+             *     **Supported elements:** `<path>`, `<rect>`, `<circle>`, `<ellipse>`,
+             *     `<line>`, `<polygon>`, `<polyline>`
+             *
+             *     **Automatically extracted:**
+             *     - Path data (converted to a single combined path)
+             *     - Fill color (from `fill` attribute or `style`)
+             *     - Stroke color and width (from attributes or `style`)
+             *     - Dimensions (from `width`/`height` or `viewBox`)
+             *     - Opacity (from `opacity` attribute)
+             *
+             *     **Important:** When using `src`, no other properties (shape, fill, stroke, etc.)
+             *     are allowed. All styling must be defined within the SVG markup itself.
+             * @example <svg width="100" height="100"><circle cx="50" cy="50" r="40" fill="#3498db"/></svg>
+             */
+            src?: string;
+            /**
+             * @description The shape definition using primitives. The `type` property within determines
+             *     the shape kind and its specific properties.
+             *
+             *     **Important:** When using `shape`, the `src` property is not allowed.
              */
-            shape: components["schemas"]["SvgShape"];
+            shape?: components["schemas"]["SvgShape"];
             /**
              * @description Fill properties for the shape interior.
              *     Can be a solid color or a gradient (linear/radial).
              *     If omitted, the shape will have no fill (transparent interior).
+             *
+             *     **Note:** Only allowed when using `shape`, not with `src`.
              */
             fill?: components["schemas"]["SvgFill"];
             /**
              * @description Stroke (outline) properties for the shape.
              *     If omitted, the shape will have no stroke (no outline).
+             *
+             *     **Note:** Only allowed when using `shape`, not with `src`.
              */
             stroke?: components["schemas"]["SvgStroke"];
             /**
              * @description Drop shadow properties for the shape.
              *     Creates a shadow effect behind the shape.
+             *
+             *     **Note:** Only allowed when using `shape`, not with `src`.
              */
             shadow?: components["schemas"]["SvgShadow"];
             /**
              * @description Transform properties for positioning, rotating, and scaling the shape.
              *     The transform is applied relative to the transformation origin.
+             *
+             *     **Note:** Only allowed when using `shape`, not with `src`.
              */
             transform?: components["schemas"]["SvgTransform"];
             /**
              * @description The overall opacity of the entire shape (including fill, stroke, and shadow).
              *     `1` is fully opaque, `0` is fully transparent.
              *     This is applied on top of individual fill/stroke/shadow opacity values.
+             *
+             *     **Note:** Only allowed when using `shape`, not with `src`.
              * @default 1
              * @example 1
              */
@@ -1255,6 +1303,8 @@ export interface components {
              * @description The width of the bounding box in pixels.
              *     If specified, the shape may be scaled to fit within this width.
              *     If omitted, the shape uses its natural dimensions.
+             *
+             *     **Note:** Only allowed when using `shape`, not with `src`.
              * @example 400
              */
             width?: number;
@@ -1262,6 +1312,8 @@ export interface components {
              * @description The height of the bounding box in pixels.
              *     If specified, the shape may be scaled to fit within this height.
              *     If omitted, the shape uses its natural dimensions.
+             *
+             *     **Note:** Only allowed when using `shape`, not with `src`.
              * @example 300
              */
             height?: number;