From 5234e45616752fba255081896dfd713730112ce0 Mon Sep 17 00:00:00 2001 From: jramma Date: Wed, 18 Feb 2026 17:52:25 +0100 Subject: [PATCH 01/14] Add Spanish documentation in folder /src/content/docs/es/storage-api. New files: - api-endpoint.mdx - index.mdx - javascript-helpers.mx --- .../docs/es/storage-api/api-endpoint.mdx | 140 ++++++++++++++++++ src/content/docs/es/storage-api/index.mdx | 93 ++++++++++++ .../es/storage-api/javascript-helpers.mdx | 55 +++++++ 3 files changed, 288 insertions(+) create mode 100644 src/content/docs/es/storage-api/api-endpoint.mdx create mode 100644 src/content/docs/es/storage-api/index.mdx create mode 100644 src/content/docs/es/storage-api/javascript-helpers.mdx diff --git a/src/content/docs/es/storage-api/api-endpoint.mdx b/src/content/docs/es/storage-api/api-endpoint.mdx new file mode 100644 index 00000000..14a48e0d --- /dev/null +++ b/src/content/docs/es/storage-api/api-endpoint.mdx @@ -0,0 +1,140 @@ +--- +i18nReady: true +title: API Endpoint +description: Learn about the API endpoints available in the StudioCMS Storage API. +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 4 +sidebar: + order: 3 + badge: + text: NEW + variant: success +--- + +import ReadMore from '~/components/ReadMore.astro'; +import { Aside } from '@astrojs/starlight/components'; + +The Storage API exposes endpoints that can be accessed via HTTP requests. The following sections describe the available endpoints and their usage. + + + +### Method: PUT + +To upload or update a file in the storage system, you can use the `PUT` method on the `/studiocms_api/storage/manager` endpoint. + +```http title="Storage API - PUT /studiocms_api/storage/manager" +PUT /studiocms_api/storage/manager HTTP/1.1 +Host: example.com +Content-Type: application/octet-stream +Accept: application/json +Headers: + x-storage-key: my-file.txt + + +``` + +#### Successful Response + +```http title="Storage API - PUT Success Response" +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "message": "string", + "key": "string" +} +``` + +#### Error Response + +```http title="Storage API - PUT Error Response" +HTTP/1.1 4XX/5XX Error +Content-Type: application/json + +{ + "error": "string" +} +``` + +### Method: POST + +```http title="Storage API - POST /studiocms_api/storage/manager" +POST /studiocms_api/storage/manager HTTP/1.1 +Host: example.com +Content-Type: application/json +Accept: application/json + +{ + "action": "resolveUrl | publicUrl | upload | list | delete | rename | download | cleanup | mappings | test", + ...additional parameters based on action... +} +``` + +#### Actions + +- `resolveUrl` + - **Params:** `{ identifier: string }` + - **Response:** [`UrlMetadata`](#urlmetadata) +- `publicUrl` + - **Params:** `{ key: string }` + - **Response:** [`UrlMetadata`](#urlmetadata) `& { identifier: string }` +- `upload` + - **Params:** `{ key: string, contentType: string }` + - **Response:** `{ url: string, key: string }` +- `list` + - **Params:** `{ prefix?: string, key?: string }` + - **Response:** `{ files:` [`File[]`](#file) `}` +- `delete` + - **Params:** `{ key: string }` + - **Response:** `{ success: boolean }` +- `rename` + - **Params:** `{ key: string, newKey: string }` + - **Response:** `{ success: boolean, newKey: string }` +- `download` + - **Params:** `{ key: string }` + - **Response:** `{ url: string }` +- `cleanup` + - **Params:** `N/A` + - **Response:** `{ deletedCount: number }` +- `mappings` + - **Params:** `N/A` + - **Response:** `{ mappings:` [`UrlMetadata[]`](#urlmetadata) `}` +- `test` + - **Params:** `N/A` + - **Response:** `{ success: boolean, message: string, provider: string }` + +#### Error Response + +```http title="Storage API - POST Error Response" +HTTP/1.1 4XX/5XX Error +Content-Type: application/json + +{ + "error": "string" +} +``` + +## Types + +### UrlMetadata + +```ts +export interface UrlMetadata { + url: string; + isPermanent: boolean; + expiresAt?: number; // Unix timestamp in ms +} +``` + +### File + +```ts +export interface File { + key: string | undefined; + size: number | undefined; + lastModified: Date | undefined; +} +``` \ No newline at end of file diff --git a/src/content/docs/es/storage-api/index.mdx b/src/content/docs/es/storage-api/index.mdx new file mode 100644 index 00000000..c55aca08 --- /dev/null +++ b/src/content/docs/es/storage-api/index.mdx @@ -0,0 +1,93 @@ +--- +i18nReady: true +title: Overview +description: Learn about the Storage API in StudioCMS +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 4 +sidebar: + order: 1 + badge: + text: NEW + variant: success +--- + +import ReadMore from '~/components/ReadMore.astro'; +import { Aside } from '@astrojs/starlight/components'; + +The Storage API in StudioCMS provides a unified way to manage and interact with various storage backends. It abstracts the complexities of different storage systems, allowing developers to work with a consistent interface regardless of the underlying technology. + +## How it Works + +The Storage API is designed to be flexible and extensible. It supports multiple storage backends, including local file systems, cloud storage services, and databases. Developers can choose the storage backend that best fits their needs and easily switch between them without changing their application code. + +## Manager plugins + +The Storage API uses manager plugins to handle different storage backends. Each manager plugin implements a specific storage system and provides methods for common operations such as reading, writing, and deleting files. + +An example of a manager built-in to StudioCMS is the `no-op` manager, which performs no operations and tells StudioCMS not to enable any of its storage features. + +### Example of the No-op Manager + +```ts twoslash title="NoOpStorageService.ts" +import type { + AuthorizationType, + ContextDriverDefinition, + StorageAPIEndpointFn, + StorageApiBuilderDefinition, + UrlMappingServiceDefinition, +} from 'studiocms/storage-manager/definitions'; + +/** + * A No-Op Storage Service that implements the StorageApiBuilderDefinition interface. + * + * This service provides placeholder implementations for storage API endpoints, + * returning a 501 Not Implemented response for both POST and PUT requests. + * + * @typeParam C - The context type. + * @typeParam R - The response type. + */ +export default class NoOpStorageService implements + StorageApiBuilderDefinition { + driver: ContextDriverDefinition; + urlMappingService: UrlMappingServiceDefinition; + + constructor( + driver: ContextDriverDefinition, + urlMappingService: UrlMappingServiceDefinition + ) { + this.driver = driver; + this.urlMappingService = urlMappingService; + } + + #sharedResponse() { + return { data: { error: 'noStorageConfigured' }, status: 501 }; + } + + getPOST(_?: AuthorizationType): StorageAPIEndpointFn { + return this.driver.handleEndpoint(async () => this.#sharedResponse()); + } + + getPUT(_?: AuthorizationType): StorageAPIEndpointFn { + return this.driver.handleEndpoint(async () => this.#sharedResponse()); + } +} +``` + +### Configuring a Manager + +To configure a storage manager in StudioCMS, you need to specify the desired manager plugin in your StudioCMS configuration file. To do so you must install the manager plugin package and then add it to the `storageManager` property in your `studiocms.config.*` file. + +```ts twoslash title="studiocms.config.mjs" {5} +import { defineStudioCMSConfig } from "studiocms/config"; +import s3Storage from '@studiocms/s3-storage'; + +export default defineStudioCMSConfig({ + storageManager: s3Storage(), + // other configuration options +}) +``` + + +For available storage manager plugins, see the [Package catalog](/en/package-catalog#storage-managers). + \ No newline at end of file diff --git a/src/content/docs/es/storage-api/javascript-helpers.mdx b/src/content/docs/es/storage-api/javascript-helpers.mdx new file mode 100644 index 00000000..1ad8344a --- /dev/null +++ b/src/content/docs/es/storage-api/javascript-helpers.mdx @@ -0,0 +1,55 @@ +--- +i18nReady: true +title: JavaScript Helpers +description: Learn about the JavaScript helpers available in the StudioCMS Storage API. +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 4 +sidebar: + order: 2 + badge: + text: NEW + variant: success +--- + +import ReadMore from '~/components/ReadMore.astro'; +import { Aside } from '@astrojs/starlight/components'; + +The StudioCMS Storage API provides several JavaScript helpers to facilitate interaction with storage backends. These helpers simplify tasks such as resolving storage identifiers and keys, as well as providing type definitions for better type safety and code completion. + +## JavaScript helpers + +```ts twoslash title="storage-api-example.ts" +import { + resolveStorageIdentifier, + resolveStorageKey, +} from 'studiocms/storage-api'; + +const storageIdentifier = await resolveStorageIdentifier('storage-file://my-file.txt', { + baseUrl: 'https://example.com/', // Use the value of `site` from "astro:config/server" +}); + +const storageKey = await resolveStorageKey('my-file.txt', { + baseUrl: 'https://example.com/', // Use the value of `site` from "astro:config/server" +}); +``` + +## JavaScript Types + +```ts twoslash title="storage-api-types.ts" +import type { + ContextJsonBody, + AuthorizationType, + ParsedContext, + UrlMetadata, + UrlMapping, + ContextHandler, + ContextHandlerFn, + ContextDriverDefinition, + StorageAPIEndpointFn, + StorageApiBuilderDefinition, + UrlMappingDatabaseDefinition, + UrlMappingServiceDefinition, + APICoreDefinition +} from 'studiocms/storage-api'; +``` \ No newline at end of file From a6aa2c18cc332265d1cb264314ee35e4df95ed12 Mon Sep 17 00:00:00 2001 From: jramma Date: Wed, 18 Feb 2026 18:16:39 +0100 Subject: [PATCH 02/14] Add missing docs in folder /es/storage-api New files: - api-endpoint.mdx - index.mdx - javascript-helpers.mx --- .../docs/es/storage-api/api-endpoint.mdx | 90 +++++++++---------- src/content/docs/es/storage-api/index.mdx | 48 +++++----- .../es/storage-api/javascript-helpers.mdx | 24 ++--- 3 files changed, 81 insertions(+), 81 deletions(-) diff --git a/src/content/docs/es/storage-api/api-endpoint.mdx b/src/content/docs/es/storage-api/api-endpoint.mdx index 14a48e0d..5186b9ec 100644 --- a/src/content/docs/es/storage-api/api-endpoint.mdx +++ b/src/content/docs/es/storage-api/api-endpoint.mdx @@ -1,44 +1,44 @@ --- i18nReady: true -title: API Endpoint -description: Learn about the API endpoints available in the StudioCMS Storage API. +title: Endpoint de API +description: Aprende sobre los endpoints de API disponibles en la API de almacenamiento de StudioCMS. tableOfContents: minHeadingLevel: 2 maxHeadingLevel: 4 sidebar: order: 3 badge: - text: NEW + text: NUEVO variant: success --- import ReadMore from '~/components/ReadMore.astro'; import { Aside } from '@astrojs/starlight/components'; -The Storage API exposes endpoints that can be accessed via HTTP requests. The following sections describe the available endpoints and their usage. +La API de almacenamiento expone endpoints a los que se puede acceder mediante solicitudes HTTP. Las siguientes secciones describen los endpoints disponibles y su uso. -