From 35268d0f44c686ccb120e6f41d32666f460a1d38 Mon Sep 17 00:00:00 2001 From: Rak Siva Date: Mon, 8 Sep 2025 16:10:29 -0600 Subject: [PATCH 1/3] docs: add sdk reference pages --- .../config/vocabularies/Suga/accept.txt | 2 + docs/docs.json | 31 +++ docs/sdk-reference/go/overview.mdx | 32 +++ docs/sdk-reference/go/storage.mdx | 224 ++++++++++++++++++ docs/sdk-reference/node/overview.mdx | 39 +++ docs/sdk-reference/node/storage.mdx | 172 ++++++++++++++ docs/sdk-reference/overview.mdx | 23 ++ docs/sdk-reference/python/overview.mdx | 29 +++ docs/sdk-reference/python/storage.mdx | 170 +++++++++++++ 9 files changed, 722 insertions(+) create mode 100644 docs/sdk-reference/go/overview.mdx create mode 100644 docs/sdk-reference/go/storage.mdx create mode 100644 docs/sdk-reference/node/overview.mdx create mode 100644 docs/sdk-reference/node/storage.mdx create mode 100644 docs/sdk-reference/overview.mdx create mode 100644 docs/sdk-reference/python/overview.mdx create mode 100644 docs/sdk-reference/python/storage.mdx diff --git a/docs/.vale/styles/config/vocabularies/Suga/accept.txt b/docs/.vale/styles/config/vocabularies/Suga/accept.txt index 5d22e728..23a8171c 100644 --- a/docs/.vale/styles/config/vocabularies/Suga/accept.txt +++ b/docs/.vale/styles/config/vocabularies/Suga/accept.txt @@ -10,6 +10,8 @@ Planetscale liquibase allowlisting cdktf +Presigned +presigned # Defaults from mintlify Mintlify diff --git a/docs/docs.json b/docs/docs.json index d85c73a7..e16bbcad 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -35,6 +35,37 @@ ] } ] + }, + { + "anchor": "SDK Reference", + "icon": "code", + "groups": [ + { + "group": "Overview", + "pages": ["sdk-reference/overview"] + }, + { + "group": "Python", + "pages": [ + "sdk-reference/python/overview", + "sdk-reference/python/storage" + ] + }, + { + "group": "Node.js", + "pages": [ + "sdk-reference/node/overview", + "sdk-reference/node/storage" + ] + }, + { + "group": "Go", + "pages": [ + "sdk-reference/go/overview", + "sdk-reference/go/storage" + ] + } + ] }, { "anchor": "CLI Reference", diff --git a/docs/sdk-reference/go/overview.mdx b/docs/sdk-reference/go/overview.mdx new file mode 100644 index 00000000..0435735e --- /dev/null +++ b/docs/sdk-reference/go/overview.mdx @@ -0,0 +1,32 @@ +--- +title: "Overview" +description: "Go SDK for Suga infrastructure resources" +--- + +## Import + +```go +import "example/suga" +``` + +## Usage + +```go +// Initialize client +app, err := suga.NewClient() +if err != nil { + log.Fatal(err) +} + +// Access your resources (names from your suga.yaml) +app.Files.Write("key", []byte("data")) +content, err := app.Files.Read("key") +``` + +## Available Resources + + + + Object storage operations - read, write, delete, list files + + \ No newline at end of file diff --git a/docs/sdk-reference/go/storage.mdx b/docs/sdk-reference/go/storage.mdx new file mode 100644 index 00000000..6dc9e1d7 --- /dev/null +++ b/docs/sdk-reference/go/storage.mdx @@ -0,0 +1,224 @@ +--- +title: Storage +description: Storage resources provide methods for interacting with cloud storage in your Suga infrastructure. +--- + +## Methods + +### Read + +Read a file from the bucket. + +```go +func (c *Bucket) Read(key string) ([]byte, error) +``` + +#### Parameters + + + The key/path of the file to read + + +#### Returns + + + The file contents as a byte slice + + + + Error if the operation fails + + +**Example:** + +```go +content, err := app.Files.Read("path/to/file.txt") +if err != nil { + log.Fatal(err) +} +fmt.Println(string(content)) +``` + +### Write + +Write a file to the bucket. + +```go +func (c *Bucket) Write(key string, data []byte) error +``` + +#### Parameters + + + The key/path where the file should be stored + + + + The file contents as a byte slice + + +#### Returns + + + Error if the operation fails + + +**Example:** + +```go +err := app.Files.Write("path/to/file.txt", []byte("Hello, World!")) +if err != nil { + log.Fatal(err) +} +``` + +### Delete + +Delete a file from the bucket. + +```go +func (c *Bucket) Delete(key string) error +``` + +#### Parameters + + + The key/path of the file to delete + + +#### Returns + + + Error if the operation fails + + +**Example:** + +```go +err := app.Files.Delete("path/to/file.txt") +if err != nil { + log.Fatal(err) +} +``` + +### List + +List files in the bucket with a given prefix. + +```go +func (c *Bucket) List(prefix string) ([]string, error) +``` + +#### Parameters + + + Filter results to keys starting with this prefix + + +#### Returns + + + Slice of file keys matching the prefix + + + + Error if the operation fails + + +**Example:** + +```go +// List all files +files, err := app.Files.List("") +if err != nil { + log.Fatal(err) +} + +// List files in a specific directory +docs, err := app.Files.List("documents/") +if err != nil { + log.Fatal(err) +} + +for _, file := range docs { + fmt.Println(file) +} +``` + +### Exists + +Check if a file exists in the bucket. + +```go +func (c *Bucket) Exists(key string) (bool, error) +``` + +#### Parameters + + + The key/path of the file to check + + +#### Returns + + + True if the file exists, false otherwise + + + + Error if the operation fails + + +**Example:** + +```go +exists, err := app.Files.Exists("config.json") +if err != nil { + log.Fatal(err) +} + +if exists { + content, _ := app.Files.Read("config.json") + // Process content +} +``` + +### Presigned URLs + +Generate presigned URLs for secure file access without exposing credentials. + +```go +func (c *Bucket) GetDownloadURL(key string, opts ...PresignUrlOption) (string, error) +func (c *Bucket) GetUploadURL(key string, opts ...PresignUrlOption) (string, error) +``` + +#### Parameters + + + The key/path of the file + + + + Optional configuration with WithPresignUrlExpiry(duration) + + +#### Returns + + + The presigned URL for the file + + + + Error if the operation fails + + +**Example:** + +```go +// Download URL (default 5 minute expiry) +downloadURL, err := app.Files.GetDownloadURL("document.pdf") + +// Upload URL with custom expiry (1 hour) +uploadURL, err := app.Files.GetUploadURL("uploads/newfile.pdf", + suga.WithPresignUrlExpiry(time.Hour)) +``` \ No newline at end of file diff --git a/docs/sdk-reference/node/overview.mdx b/docs/sdk-reference/node/overview.mdx new file mode 100644 index 00000000..a6701a73 --- /dev/null +++ b/docs/sdk-reference/node/overview.mdx @@ -0,0 +1,39 @@ +--- +title: "Overview" +description: "Node.js SDK for Suga infrastructure resources" +--- + + +## Import + + + + ```typescript + import { SugaClient } from './suga/client'; + ``` + + + ```javascript + const { SugaClient } = require('./suga/client'); + ``` + + + +## Usage + +```javascript +// Initialize client +const suga = new SugaClient(); + +// Access your resources (names from your suga.yaml) +await suga.image.write("key", Buffer.from("data")); +const content = await suga.image.read("key"); +``` + +## Available Resources + + + + Object storage operations - read, write, delete, list files + + \ No newline at end of file diff --git a/docs/sdk-reference/node/storage.mdx b/docs/sdk-reference/node/storage.mdx new file mode 100644 index 00000000..562d2103 --- /dev/null +++ b/docs/sdk-reference/node/storage.mdx @@ -0,0 +1,172 @@ +--- +title: Storage +description: Storage resources provide async methods for interacting with cloud storage in your Suga infrastructure. +--- + +## Methods + +### read + +Read a file from the bucket. + +```typescript +async read(key: string): Promise +``` + +#### Parameters + + + The key/path of the file to read + + +#### Returns + + + The file contents as a Buffer + + +**Example:** + +```typescript +const content = await bucket.read("path/to/file.txt"); +console.log(content.toString('utf-8')); +``` + +### write + +Write a file to the bucket. + +```typescript +async write(key: string, data: Buffer): Promise +``` + +#### Parameters + + + The key/path where the file should be stored + + + + The file contents as a Buffer + + +**Example:** + +```typescript +await bucket.write("path/to/file.txt", Buffer.from("Hello, World!")); +``` + +### delete + +Delete a file from the bucket. + +```typescript +async delete(key: string): Promise +``` + +#### Parameters + + + The key/path of the file to delete + + +**Example:** + +```typescript +await bucket.delete("path/to/file.txt"); +``` + +### list + +List files in the bucket with a given prefix. + +```typescript +async list(prefix: string): Promise +``` + +#### Parameters + + + Filter results to keys starting with this prefix + + +#### Returns + + + Array of file keys matching the prefix + + +**Example:** + +```typescript +// List all files with empty prefix +const allFiles = await bucket.list(""); + +// List files in a specific directory +const docs = await bucket.list("documents/"); +``` + +### exists + +Check if a file exists in the bucket. + +```typescript +async exists(key: string): Promise +``` + +#### Parameters + + + The key/path of the file to check + + +#### Returns + + + True if the file exists, false otherwise + + +**Example:** + +```typescript +if (await bucket.exists("config.json")) { + const config = await bucket.read("config.json"); +} +``` + +### Presigned URLs + +Generate presigned URLs for secure file access without exposing credentials. + +```typescript +async getDownloadUrl(key: string, options?: {expiry: number}): Promise +async getUploadUrl(key: string, options?: {expiry: number}): Promise +``` + +#### Parameters + + + The key/path of the file + + + + Configuration with expiry in seconds + + +#### Returns + + + The presigned URL for the file + + +**Example:** + +```typescript +// Download URL (default 5 minute expiry) +const downloadUrl = await suga.image.getDownloadUrl("document.pdf"); + +// Upload URL with custom expiry (1 hour) +const uploadUrl = await suga.image.getUploadUrl("uploads/newfile.pdf", { + expiry: 3600 +}); +``` \ No newline at end of file diff --git a/docs/sdk-reference/overview.mdx b/docs/sdk-reference/overview.mdx new file mode 100644 index 00000000..ecc559ae --- /dev/null +++ b/docs/sdk-reference/overview.mdx @@ -0,0 +1,23 @@ +--- +title: "SDK Reference" +description: "Language-specific SDK documentation for Suga" +--- + +SDKs for multiple programming languages to interact with your infrastructure resources. + +## Getting Started + +To generate SDK clients for your project, use the +[`suga generate`](/cli/generate) command. + +## Available SDKs + + + + + + + + + For installation and setup instructions, see the [Quickstart Guide](/quickstart). + \ No newline at end of file diff --git a/docs/sdk-reference/python/overview.mdx b/docs/sdk-reference/python/overview.mdx new file mode 100644 index 00000000..4d342aec --- /dev/null +++ b/docs/sdk-reference/python/overview.mdx @@ -0,0 +1,29 @@ +--- +title: "Overview" +description: "Python SDK for Suga infrastructure resources" +--- + +## Import + +```python +from suga_gen.client import SugaClient +``` + +## Usage + +```python +# Initialize client +suga = SugaClient() + +# Access your resources (names from your suga.yaml) +suga.image.write("key", b"data") +content = suga.image.read("key") +``` + +## Available Resources + + + + Object storage operations - read, write, delete, list files + + \ No newline at end of file diff --git a/docs/sdk-reference/python/storage.mdx b/docs/sdk-reference/python/storage.mdx new file mode 100644 index 00000000..74dc1811 --- /dev/null +++ b/docs/sdk-reference/python/storage.mdx @@ -0,0 +1,170 @@ +--- +title: Storage +description: Storage resources provide methods for interacting with cloud storage in your Suga infrastructure. +--- + +## Methods + +### read + +Read a file from the bucket. + +```python +def read(key: str) -> bytes +``` + +#### Parameters + + + The key/path of the file to read + + +#### Returns + + + The file contents as bytes + + +**Example:** + +```python +content = bucket.read("path/to/file.txt") +print(content.decode('utf-8')) +``` + +### write + +Write a file to the bucket. + +```python +def write(key: str, data: bytes) -> None +``` + +#### Parameters + + + The key/path where the file should be stored + + + + The file contents as bytes + + +**Example:** + +```python +bucket.write("path/to/file.txt", b"Hello, World!") +``` + +### delete + +Delete a file from the bucket. + +```python +def delete(key: str) -> None +``` + +#### Parameters + + + The key/path of the file to delete + + +**Example:** + +```python +bucket.delete("path/to/file.txt") +``` + +### list + +List files in the bucket with an optional prefix filter. + +```python +def list(prefix: str = "") -> List[str] +``` + +#### Parameters + + + Filter results to keys starting with this prefix + + +#### Returns + + + List of file keys matching the prefix + + +**Example:** + +```python +# List all files +all_files = bucket.list() + +# List files in a specific directory +docs = bucket.list("documents/") +``` + +### exists + +Check if a file exists in the bucket. + +```python +def exists(key: str) -> bool +``` + +#### Parameters + + + The key/path of the file to check + + +#### Returns + + + True if the file exists, False otherwise + + +**Example:** + +```python +if bucket.exists("config.json"): + config = bucket.read("config.json") +``` + +### Presigned URLs + +Generate presigned URLs for secure file access without exposing credentials. + +```python +def get_download_url(key: str, options: Optional[PresignUrlOptions] = None) -> str +def get_upload_url(key: str, options: Optional[PresignUrlOptions] = None) -> str +``` + +#### Parameters + + + The key/path of the file + + + + Configuration with expiry in seconds + + +#### Returns + + + The presigned URL for the file + + +**Example:** + +```python +# Download URL (default 5 minute expiry) +download_url = suga.image.get_download_url("document.pdf") + +# Upload URL with custom expiry (1 hour) +upload_url = suga.image.get_upload_url("uploads/newfile.pdf", + PresignUrlOptions(expiry=3600)) +``` \ No newline at end of file From ff43bfcf40fe1e492bdaa2829a940ec7707adef2 Mon Sep 17 00:00:00 2001 From: Rak Siva Date: Tue, 9 Sep 2025 08:58:46 -0600 Subject: [PATCH 2/3] docs: refresh content --- docs/docs.json | 52 +++++++++++++------------- docs/sdk-reference/go/overview.mdx | 25 +++++++++++-- docs/sdk-reference/go/storage.mdx | 18 ++++----- docs/sdk-reference/node/overview.mdx | 24 ++++++++++-- docs/sdk-reference/node/storage.mdx | 27 ++++++------- docs/sdk-reference/overview.mdx | 44 +++++++++++++++++----- docs/sdk-reference/python/overview.mdx | 25 +++++++++++-- docs/sdk-reference/python/storage.mdx | 18 ++++----- 8 files changed, 157 insertions(+), 76 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index e16bbcad..74d86967 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -37,6 +37,32 @@ ] }, { + "anchor": "CLI Reference", + "icon": "terminal", + "groups": [ + { + "group": "Commands", + "pages": [ + "cli/introduction", + "cli/access-token", + "cli/build", + "cli/completion", + "cli/config", + "cli/dev", + "cli/edit", + "cli/generate", + "cli/init", + "cli/login", + "cli/logout", + "cli/new", + "cli/team", + "cli/templates", + "cli/version" + ] + } + ] + }, + { "anchor": "SDK Reference", "icon": "code", "groups": [ @@ -66,32 +92,6 @@ ] } ] - }, - { - "anchor": "CLI Reference", - "icon": "terminal", - "groups": [ - { - "group": "Commands", - "pages": [ - "cli/introduction", - "cli/access-token", - "cli/build", - "cli/completion", - "cli/config", - "cli/dev", - "cli/edit", - "cli/generate", - "cli/init", - "cli/login", - "cli/logout", - "cli/new", - "cli/team", - "cli/templates", - "cli/version" - ] - } - ] } ], "global": { diff --git a/docs/sdk-reference/go/overview.mdx b/docs/sdk-reference/go/overview.mdx index 0435735e..e766010e 100644 --- a/docs/sdk-reference/go/overview.mdx +++ b/docs/sdk-reference/go/overview.mdx @@ -3,6 +3,25 @@ title: "Overview" description: "Go SDK for Suga infrastructure resources" --- +## Generate SDK + +Generate the Go client based on your `suga.yaml`: + +```yaml title="suga.yaml" +buckets: + image: + access: + app: + - read + - write +``` + +```bash +suga generate --go --go-out ./suga --go-package-name suga +``` + +For all available options, see the [`suga generate`](/cli/generate) command documentation. + ## Import ```go @@ -13,14 +32,14 @@ import "example/suga" ```go // Initialize client -app, err := suga.NewClient() +client, err := suga.NewClient() if err != nil { log.Fatal(err) } // Access your resources (names from your suga.yaml) -app.Files.Write("key", []byte("data")) -content, err := app.Files.Read("key") +err = client.Image.Write("file.txt", []byte("data")) +content, err := client.Image.Read("file.txt") ``` ## Available Resources diff --git a/docs/sdk-reference/go/storage.mdx b/docs/sdk-reference/go/storage.mdx index 6dc9e1d7..cb12b88f 100644 --- a/docs/sdk-reference/go/storage.mdx +++ b/docs/sdk-reference/go/storage.mdx @@ -32,7 +32,7 @@ func (c *Bucket) Read(key string) ([]byte, error) **Example:** ```go -content, err := app.Files.Read("path/to/file.txt") +content, err := client.Image.Read("path/to/file.txt") if err != nil { log.Fatal(err) } @@ -66,7 +66,7 @@ func (c *Bucket) Write(key string, data []byte) error **Example:** ```go -err := app.Files.Write("path/to/file.txt", []byte("Hello, World!")) +err := client.Image.Write("path/to/file.txt", []byte("Hello, World!")) if err != nil { log.Fatal(err) } @@ -95,7 +95,7 @@ func (c *Bucket) Delete(key string) error **Example:** ```go -err := app.Files.Delete("path/to/file.txt") +err := client.Image.Delete("path/to/file.txt") if err != nil { log.Fatal(err) } @@ -129,13 +129,13 @@ func (c *Bucket) List(prefix string) ([]string, error) ```go // List all files -files, err := app.Files.List("") +files, err := client.Image.List("") if err != nil { log.Fatal(err) } // List files in a specific directory -docs, err := app.Files.List("documents/") +docs, err := client.Image.List("documents/") if err != nil { log.Fatal(err) } @@ -172,13 +172,13 @@ func (c *Bucket) Exists(key string) (bool, error) **Example:** ```go -exists, err := app.Files.Exists("config.json") +exists, err := client.Image.Exists("file.txt") if err != nil { log.Fatal(err) } if exists { - content, _ := app.Files.Read("config.json") + content, _ := client.Image.Read("file.txt") // Process content } ``` @@ -216,9 +216,9 @@ func (c *Bucket) GetUploadURL(key string, opts ...PresignUrlOption) (string, err ```go // Download URL (default 5 minute expiry) -downloadURL, err := app.Files.GetDownloadURL("document.pdf") +downloadURL, err := client.Image.GetDownloadURL("file.txt") // Upload URL with custom expiry (1 hour) -uploadURL, err := app.Files.GetUploadURL("uploads/newfile.pdf", +uploadURL, err := client.Image.GetUploadURL("file.txt", suga.WithPresignUrlExpiry(time.Hour)) ``` \ No newline at end of file diff --git a/docs/sdk-reference/node/overview.mdx b/docs/sdk-reference/node/overview.mdx index a6701a73..4034d773 100644 --- a/docs/sdk-reference/node/overview.mdx +++ b/docs/sdk-reference/node/overview.mdx @@ -3,6 +3,24 @@ title: "Overview" description: "Node.js SDK for Suga infrastructure resources" --- +## Generate SDK + +Generate the TypeScript client based on your `suga.yaml`: + +```yaml title="suga.yaml" +buckets: + image: + access: + app: + - read + - write +``` + +```bash +suga generate --ts --ts-out ./suga +``` + +For all available options, see the [`suga generate`](/cli/generate) command documentation. ## Import @@ -23,11 +41,11 @@ description: "Node.js SDK for Suga infrastructure resources" ```javascript // Initialize client -const suga = new SugaClient(); +const client = new SugaClient(); // Access your resources (names from your suga.yaml) -await suga.image.write("key", Buffer.from("data")); -const content = await suga.image.read("key"); +await client.image.write("file.txt", Buffer.from("data")); +const content = await client.image.read("file.txt"); ``` ## Available Resources diff --git a/docs/sdk-reference/node/storage.mdx b/docs/sdk-reference/node/storage.mdx index 562d2103..a9e19c3c 100644 --- a/docs/sdk-reference/node/storage.mdx +++ b/docs/sdk-reference/node/storage.mdx @@ -28,7 +28,7 @@ async read(key: string): Promise **Example:** ```typescript -const content = await bucket.read("path/to/file.txt"); +const content = await client.image.read("path/to/file.txt"); console.log(content.toString('utf-8')); ``` @@ -53,7 +53,7 @@ async write(key: string, data: Buffer): Promise **Example:** ```typescript -await bucket.write("path/to/file.txt", Buffer.from("Hello, World!")); +await client.image.write("path/to/file.txt", Buffer.from("Hello, World!")); ``` ### delete @@ -73,7 +73,7 @@ async delete(key: string): Promise **Example:** ```typescript -await bucket.delete("path/to/file.txt"); +await client.image.delete("path/to/file.txt"); ``` ### list @@ -100,10 +100,10 @@ async list(prefix: string): Promise ```typescript // List all files with empty prefix -const allFiles = await bucket.list(""); +const allFiles = await client.image.list(""); // List files in a specific directory -const docs = await bucket.list("documents/"); +const docs = await client.image.list("documents/"); ``` ### exists @@ -129,8 +129,8 @@ async exists(key: string): Promise **Example:** ```typescript -if (await bucket.exists("config.json")) { - const config = await bucket.read("config.json"); +if (await client.image.exists("file.txt")) { + const config = await client.image.read("file.txt"); } ``` @@ -139,8 +139,8 @@ if (await bucket.exists("config.json")) { Generate presigned URLs for secure file access without exposing credentials. ```typescript -async getDownloadUrl(key: string, options?: {expiry: number}): Promise -async getUploadUrl(key: string, options?: {expiry: number}): Promise +async getDownloadUrl(key: string, options?: Partial): Promise +async getUploadUrl(key: string, options?: Partial): Promise ``` #### Parameters @@ -149,8 +149,8 @@ async getUploadUrl(key: string, options?: {expiry: number}): Promise The key/path of the file - - Configuration with expiry in seconds + + Configuration with mode and expiry in seconds #### Returns @@ -163,10 +163,11 @@ async getUploadUrl(key: string, options?: {expiry: number}): Promise ```typescript // Download URL (default 5 minute expiry) -const downloadUrl = await suga.image.getDownloadUrl("document.pdf"); +const downloadUrl = await client.image.getDownloadUrl("file.txt"); // Upload URL with custom expiry (1 hour) -const uploadUrl = await suga.image.getUploadUrl("uploads/newfile.pdf", { +const uploadUrl = await client.image.getUploadUrl("file.txt", { + mode: Mode.Write, expiry: 3600 }); ``` \ No newline at end of file diff --git a/docs/sdk-reference/overview.mdx b/docs/sdk-reference/overview.mdx index ecc559ae..c4d83f96 100644 --- a/docs/sdk-reference/overview.mdx +++ b/docs/sdk-reference/overview.mdx @@ -3,14 +3,9 @@ title: "SDK Reference" description: "Language-specific SDK documentation for Suga" --- -SDKs for multiple programming languages to interact with your infrastructure resources. +Suga automatically generates type-safe SDKs from your `suga.yaml` configuration. Define your infrastructure resources and access permissions once, then get pre-configured clients with only the methods your application needs. -## Getting Started - -To generate SDK clients for your project, use the -[`suga generate`](/cli/generate) command. - -## Available SDKs +## Available Languages @@ -18,6 +13,35 @@ To generate SDK clients for your project, use the - - For installation and setup instructions, see the [Quickstart Guide](/quickstart). - \ No newline at end of file +## How It Works + +1. **Define resources and permissions** using the Suga editor: + ```bash + suga edit + ``` + Or manually in your `suga.yaml`: + ```yaml + buckets: + images: + access: + app: + - read + - write + ``` + +2. **Generate your SDK** with access already configured: + ```bash + suga generate --python --python-out ./client + ``` + +3. **Use pre-configured resources**: + ```python + client = SugaClient() + client.images.read("file.txt") + client.images.write("file.txt") + ``` + +Your SDK automatically handles authentication, permissions, and environment differences. The same code works locally with `suga dev` and when deployed to the cloud. + + + diff --git a/docs/sdk-reference/python/overview.mdx b/docs/sdk-reference/python/overview.mdx index 4d342aec..c93f6949 100644 --- a/docs/sdk-reference/python/overview.mdx +++ b/docs/sdk-reference/python/overview.mdx @@ -3,6 +3,25 @@ title: "Overview" description: "Python SDK for Suga infrastructure resources" --- +## Generate SDK + +Generate the Python client based on your `suga.yaml`: + +```yaml title="suga.yaml" +buckets: + image: + access: + app: + - read + - write +``` + +```bash +suga generate --python --python-out ./suga_gen +``` + +For all available options, see the [`suga generate`](/cli/generate) command documentation. + ## Import ```python @@ -13,11 +32,11 @@ from suga_gen.client import SugaClient ```python # Initialize client -suga = SugaClient() +client = SugaClient() # Access your resources (names from your suga.yaml) -suga.image.write("key", b"data") -content = suga.image.read("key") +client.image.write("file.txt", b"data") +content = client.image.read("file.txt") ``` ## Available Resources diff --git a/docs/sdk-reference/python/storage.mdx b/docs/sdk-reference/python/storage.mdx index 74dc1811..84324000 100644 --- a/docs/sdk-reference/python/storage.mdx +++ b/docs/sdk-reference/python/storage.mdx @@ -28,7 +28,7 @@ def read(key: str) -> bytes **Example:** ```python -content = bucket.read("path/to/file.txt") +content = client.image.read("path/to/file.txt") print(content.decode('utf-8')) ``` @@ -53,7 +53,7 @@ def write(key: str, data: bytes) -> None **Example:** ```python -bucket.write("path/to/file.txt", b"Hello, World!") +client.image.write("path/to/file.txt", b"Hello, World!") ``` ### delete @@ -73,7 +73,7 @@ def delete(key: str) -> None **Example:** ```python -bucket.delete("path/to/file.txt") +client.image.delete("path/to/file.txt") ``` ### list @@ -100,10 +100,10 @@ def list(prefix: str = "") -> List[str] ```python # List all files -all_files = bucket.list() +all_files = client.image.list() # List files in a specific directory -docs = bucket.list("documents/") +docs = client.image.list("documents/") ``` ### exists @@ -129,8 +129,8 @@ def exists(key: str) -> bool **Example:** ```python -if bucket.exists("config.json"): - config = bucket.read("config.json") +if client.image.exists("file.txt"): + config = client.image.read("file.txt") ``` ### Presigned URLs @@ -162,9 +162,9 @@ def get_upload_url(key: str, options: Optional[PresignUrlOptions] = None) -> str ```python # Download URL (default 5 minute expiry) -download_url = suga.image.get_download_url("document.pdf") +download_url = client.image.get_download_url("file.txt") # Upload URL with custom expiry (1 hour) -upload_url = suga.image.get_upload_url("uploads/newfile.pdf", +upload_url = client.image.get_upload_url("file.txt", PresignUrlOptions(expiry=3600)) ``` \ No newline at end of file From 0394d6daa1988bf9b2bc1c39a86a2dd93bfed12d Mon Sep 17 00:00:00 2001 From: David Moore Date: Wed, 10 Sep 2025 11:40:24 +1000 Subject: [PATCH 3/3] docs: restructures sdk documentation and switch to tabs --- docs/docs.json | 90 +++++++++---------- docs/{sdk-reference/overview.mdx => sdks.mdx} | 15 ++-- .../go/overview.mdx => sdks/go.mdx} | 4 +- docs/{sdk-reference => sdks}/go/storage.mdx | 0 .../node/overview.mdx => sdks/node.mdx} | 12 +-- docs/{sdk-reference => sdks}/node/storage.mdx | 0 .../python/overview.mdx => sdks/python.mdx} | 4 +- .../python/storage.mdx | 0 8 files changed, 58 insertions(+), 67 deletions(-) rename docs/{sdk-reference/overview.mdx => sdks.mdx} (80%) rename docs/{sdk-reference/go/overview.mdx => sdks/go.mdx} (90%) rename docs/{sdk-reference => sdks}/go/storage.mdx (100%) rename docs/{sdk-reference/node/overview.mdx => sdks/node.mdx} (78%) rename docs/{sdk-reference => sdks}/node/storage.mdx (100%) rename docs/{sdk-reference/python/overview.mdx => sdks/python.mdx} (89%) rename docs/{sdk-reference => sdks}/python/storage.mdx (100%) diff --git a/docs/docs.json b/docs/docs.json index 74d86967..cf954915 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -14,9 +14,9 @@ }, "favicon": "/favicon.svg", "navigation": { - "anchors": [ + "tabs": [ { - "anchor": "Documentation", + "tab": "Docs", "icon": "book-open", "groups": [ { @@ -35,60 +35,54 @@ ] } ] - }, + }, { - "anchor": "CLI Reference", - "icon": "terminal", - "groups": [ - { - "group": "Commands", - "pages": [ - "cli/introduction", - "cli/access-token", - "cli/build", - "cli/completion", - "cli/config", - "cli/dev", - "cli/edit", - "cli/generate", - "cli/init", - "cli/login", - "cli/logout", - "cli/new", - "cli/team", - "cli/templates", - "cli/version" - ] - } + "tab": "CLI", + "icon": "square-terminal", + "pages": [ + "cli/introduction", + "cli/access-token", + "cli/build", + "cli/completion", + "cli/config", + "cli/dev", + "cli/edit", + "cli/generate", + "cli/init", + "cli/login", + "cli/logout", + "cli/new", + "cli/team", + "cli/templates", + "cli/version" ] }, - { - "anchor": "SDK Reference", + { + "tab": "SDKs", "icon": "code", - "groups": [ - { - "group": "Overview", - "pages": ["sdk-reference/overview"] - }, - { - "group": "Python", - "pages": [ - "sdk-reference/python/overview", - "sdk-reference/python/storage" - ] - }, + "groups": [ { - "group": "Node.js", - "pages": [ - "sdk-reference/node/overview", - "sdk-reference/node/storage" - ] + "group": "SDKs", + "pages": ["sdks"] }, { - "group": "Go", + "group": "Reference", "pages": [ - "sdk-reference/go/overview", - "sdk-reference/go/storage" + { + "group": "Python", + "icon": "python", + "pages": ["sdks/python", "sdks/python/storage"] + }, + { + "group": "Node.js", + "icon": "node-js", + "pages": ["sdks/node", "sdks/node/storage"] + }, + { + "group": "Go", + "icon": "golang", + "pages": ["sdks/go", "sdks/go/storage"] + } ] } ] diff --git a/docs/sdk-reference/overview.mdx b/docs/sdks.mdx similarity index 80% rename from docs/sdk-reference/overview.mdx rename to docs/sdks.mdx index c4d83f96..cf7f8f60 100644 --- a/docs/sdk-reference/overview.mdx +++ b/docs/sdks.mdx @@ -1,5 +1,5 @@ --- -title: "SDK Reference" +title: "Introduction" description: "Language-specific SDK documentation for Suga" --- @@ -8,18 +8,21 @@ Suga automatically generates type-safe SDKs from your `suga.yaml` configuration. ## Available Languages - - - + + + ## How It Works 1. **Define resources and permissions** using the Suga editor: + ```bash suga edit ``` + Or manually in your `suga.yaml`: + ```yaml buckets: images: @@ -30,6 +33,7 @@ Suga automatically generates type-safe SDKs from your `suga.yaml` configuration. ``` 2. **Generate your SDK** with access already configured: + ```bash suga generate --python --python-out ./client ``` @@ -42,6 +46,3 @@ Suga automatically generates type-safe SDKs from your `suga.yaml` configuration. ``` Your SDK automatically handles authentication, permissions, and environment differences. The same code works locally with `suga dev` and when deployed to the cloud. - - - diff --git a/docs/sdk-reference/go/overview.mdx b/docs/sdks/go.mdx similarity index 90% rename from docs/sdk-reference/go/overview.mdx rename to docs/sdks/go.mdx index e766010e..7aed4028 100644 --- a/docs/sdk-reference/go/overview.mdx +++ b/docs/sdks/go.mdx @@ -45,7 +45,7 @@ content, err := client.Image.Read("file.txt") ## Available Resources - + Object storage operations - read, write, delete, list files - \ No newline at end of file + diff --git a/docs/sdk-reference/go/storage.mdx b/docs/sdks/go/storage.mdx similarity index 100% rename from docs/sdk-reference/go/storage.mdx rename to docs/sdks/go/storage.mdx diff --git a/docs/sdk-reference/node/overview.mdx b/docs/sdks/node.mdx similarity index 78% rename from docs/sdk-reference/node/overview.mdx rename to docs/sdks/node.mdx index 4034d773..ef642b15 100644 --- a/docs/sdk-reference/node/overview.mdx +++ b/docs/sdks/node.mdx @@ -26,14 +26,10 @@ For all available options, see the [`suga generate`](/cli/generate) command docu - ```typescript - import { SugaClient } from './suga/client'; - ``` + ```typescript import {SugaClient} from './suga/client'; ``` - ```javascript - const { SugaClient } = require('./suga/client'); - ``` + ```javascript const {SugaClient} = require('./suga/client'); ``` @@ -51,7 +47,7 @@ const content = await client.image.read("file.txt"); ## Available Resources - + Object storage operations - read, write, delete, list files - \ No newline at end of file + diff --git a/docs/sdk-reference/node/storage.mdx b/docs/sdks/node/storage.mdx similarity index 100% rename from docs/sdk-reference/node/storage.mdx rename to docs/sdks/node/storage.mdx diff --git a/docs/sdk-reference/python/overview.mdx b/docs/sdks/python.mdx similarity index 89% rename from docs/sdk-reference/python/overview.mdx rename to docs/sdks/python.mdx index c93f6949..f74209db 100644 --- a/docs/sdk-reference/python/overview.mdx +++ b/docs/sdks/python.mdx @@ -42,7 +42,7 @@ content = client.image.read("file.txt") ## Available Resources - + Object storage operations - read, write, delete, list files - \ No newline at end of file + diff --git a/docs/sdk-reference/python/storage.mdx b/docs/sdks/python/storage.mdx similarity index 100% rename from docs/sdk-reference/python/storage.mdx rename to docs/sdks/python/storage.mdx