@marinoscar/platform-contract 0.1.0-next.3 → 0.1.0-next.4

package/dist/esm/storage/settings-schemas.d.ts

@@ -0,0 +1,188 @@
+import { z } from 'zod';
+import { STORAGE_SECRET_FIELD_NAMES } from './constants.js';
+/**
+ * A storage driver id: any string matching {@link STORAGE_DRIVER_ID_PATTERN}.
+ * Not an enum: an app registers drivers (`registerStorageDriver`), and the API
+ * validates the id against the registry.
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export declare const storageDriverIdSchema: z.ZodString;
+/**
+ * One driver's non-secret settings as stored: whatever that driver's
+ * `settingsSchema` declares. The contract cannot see the registry, so it
+ * checks the shape (a record) and the API validates each entry with the
+ * driver that owns it.
+ *
+ * @stability experimental
+ */
+export declare const storageDriverSettingsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/**
+ * The `drivers` record: driver id to that driver's settings.
+ *
+ * @stability experimental
+ */
+export declare const storageDriversSchema: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+/**
+ * The `drivers` record of a PATCH: `null` removes a driver's stored settings
+ * (back to its defaults), an object is merged over them.
+ *
+ * @stability experimental
+ */
+export declare const storageDriversPatchSchema: z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+/**
+ * Object-storage configuration (`storage`).
+ *
+ * `provider` is the id of the active driver; `drivers` holds every driver's own
+ * non-secret settings (`drivers.s3.bucket`, `drivers.local-fs.directory`, ...).
+ * "Not configured" is a driver whose settings are incomplete (the built-ins:
+ * `bucket === ''`), never a missing block, exactly as before drivers were
+ * pluggable.
+ *
+ * The six trailing fields are the DEPRECATED FLAT VIEW (`bucket`, `region`,
+ * `endpoint`, `accountId`, `accessKeyId`, `forcePathStyle`): optional here so a
+ * row written by an earlier release still reads (the API's read adapter folds
+ * them into `drivers.<provider>`), and filled on read from the active built-in
+ * driver's settings so existing readers of `GET /api/system-settings` see what
+ * they saw. They are never written by the API; a write stores `provider` and
+ * `drivers` only. Their semantics are the built-in drivers':
+ *
+ *  - `bucket` empty means not configured; `region` empty means not stated (R2
+ *    wants `auto`); `endpoint` empty means "derive it, or use the SDK's host"
+ *    and an explicit value always wins; `accountId` is R2 only;
+ *  - `forcePathStyle` is TRI-STATE, `null` meaning "use this vendor's
+ *    convention" (path style for `s3compatible`, virtual-host for `s3` and
+ *    `r2`).
+ *
+ * NO `.default()` ON ANY FIELD: the defaults live in the namespace declaration
+ * (`STORAGE_SYSTEM_SETTINGS`) and nowhere else.
+ *
+ * NO SECRET, EVER: a driver's secrets are declared by the driver and stored in
+ * the encrypted credential store. `StorageSettingsCarriesNoSecret` below fails
+ * to compile if a secret-named field is added.
+ *
+ * @stability experimental
+ */
+export declare const systemStorageSchema: z.ZodObject<{
+    provider: z.ZodString;
+    drivers: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    bucket: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    accountId: z.ZodOptional<z.ZodString>;
+    accessKeyId: z.ZodOptional<z.ZodString>;
+    forcePathStyle: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+}, z.core.$strip>;
+/**
+ * The stored `storage` namespace value, inferred.
+ *
+ * @stability experimental
+ */
+export type SystemStorageValue = z.infer<typeof systemStorageSchema>;
+/**
+ * `storage`, one level deep: the canonical partial. Every field optional; an
+ * empty string in a flat field is a meaningful value (it clears the field), so
+ * the merge uses `??`, and `forcePathStyle` is the one nullable field (absent
+ * leaves it alone, `null` restores the vendor convention).
+ *
+ * @stability experimental
+ */
+export declare const systemStoragePatchSchema: z.ZodObject<{
+    provider: z.ZodOptional<z.ZodString>;
+    drivers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+    bucket: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    accountId: z.ZodOptional<z.ZodString>;
+    accessKeyId: z.ZodOptional<z.ZodString>;
+    forcePathStyle: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+}, z.core.$strip>;
+/**
+ * The `storage` branch of the `PUT /api/system-settings` body (no secret, ever).
+ * Send `provider` and `drivers`; the six flat fields are accepted as aliases of
+ * `drivers.<provider>` for clients written before drivers were pluggable.
+ *
+ * @stability experimental
+ */
+export declare const storageSettingsSchema: z.ZodObject<{
+    provider: z.ZodString;
+    drivers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    bucket: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    accountId: z.ZodOptional<z.ZodString>;
+    accessKeyId: z.ZodOptional<z.ZodString>;
+    forcePathStyle: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+}, z.core.$strip>;
+/**
+ * The `storage` branch of the `PATCH /api/system-settings` body; `''` clears a field, absent leaves it.
+ *
+ * @stability experimental
+ */
+export declare const storageSettingsPatchSchema: z.ZodObject<{
+    provider: z.ZodOptional<z.ZodString>;
+    drivers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+    bucket: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    accountId: z.ZodOptional<z.ZodString>;
+    accessKeyId: z.ZodOptional<z.ZodString>;
+    forcePathStyle: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+}, z.core.$strip>;
+/**
+ * The `storage` branch of the `GET /api/system-settings` response (no secret,
+ * ever). `provider` and `drivers` are the stored shape; the six flat fields are
+ * the deprecated read view of the active built-in driver (empty strings and
+ * `null` when the active driver is not a built-in).
+ *
+ * @stability experimental
+ */
+export declare const storageResponseSchema: z.ZodObject<{
+    provider: z.ZodString;
+    drivers: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    bucket: z.ZodString;
+    region: z.ZodString;
+    endpoint: z.ZodString;
+    accountId: z.ZodString;
+    accessKeyId: z.ZodString;
+    forcePathStyle: z.ZodNullable<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * The PUT body's `storage` branch, inferred.
+ *
+ * @stability stable
+ */
+export type StorageSettingsInput = z.infer<typeof storageSettingsSchema>;
+/**
+ * The PATCH body's `storage` branch, inferred.
+ *
+ * @stability stable
+ */
+export type StorageSettingsPatchInput = z.infer<typeof storageSettingsPatchSchema>;
+/**
+ * The stored partial, inferred.
+ *
+ * @stability stable
+ */
+export type SystemStoragePatchValue = z.infer<typeof systemStoragePatchSchema>;
+/**
+ * The GET response's `storage` branch, inferred.
+ *
+ * @stability stable
+ */
+export type StorageSettingsResponse = z.infer<typeof storageResponseSchema>;
+/**
+ * `true` while {@link SystemStorageValue} has no field named in
+ * `STORAGE_SECRET_FIELD_NAMES`; `never` (a compile error below) otherwise.
+ *
+ * @stability stable
+ */
+export type StorageSettingsCarriesNoSecret = Extract<keyof SystemStorageValue, (typeof STORAGE_SECRET_FIELD_NAMES)[number]> extends never ? true : never;
+/**
+ * The value that makes {@link StorageSettingsCarriesNoSecret} a compile-time check.
+ *
+ * @stability stable
+ */
+export declare const STORAGE_SETTINGS_CARRIES_NO_SECRET: StorageSettingsCarriesNoSecret;
+//# sourceMappingURL=settings-schemas.d.ts.map

package/dist/esm/storage/settings-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-schemas.d.ts","sourceRoot":"","sources":["../../../src/storage/settings-schemas.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAA6B,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAEvF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,aAA8C,CAAC;AAEjF;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,wCAAoC,CAAC;AAE7E;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,kEAA+D,CAAC;AAEjG;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,iFAA0E,CAAC;AAEjH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;iBAiB9B,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;iBAqBnC,CAAC;AAeH;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;iBAiBhC,CAAC;AAOH;;;;GAIG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;iBAA2B,CAAC;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;iBAoBhC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAEnF;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE/E;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAY5E;;;;;GAKG;AACH,MAAM,MAAM,8BAA8B,GACxC,OAAO,CAAC,MAAM,kBAAkB,EAAE,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;AAE9G;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,EAAE,8BAAqC,CAAC"}

package/dist/esm/storage/settings-schemas.js

@@ -0,0 +1,220 @@
+// =============================================================================
+// Storage: the `storage` system-settings namespace's schemas (issue #736)
+// =============================================================================
+//
+// PP-14.7 (#925): THE NAMESPACE STORES `provider` (a driver id, any
+// `STORAGE_DRIVER_ID_PATTERN` string) AND `drivers` (a record of each driver's
+// own non-secret settings, validated by that driver in the API). The six flat
+// fields the namespace used to store (`bucket` ... `forcePathStyle`) survive
+// as a deprecated READ VIEW of the active built-in driver and as accepted
+// aliases on PUT and PATCH, so no existing client, script or row breaks.
+//
+// The five schemas the namespace declaration of
+// `@marinoscar/platform-api/storage` (`STORAGE_SYSTEM_SETTINGS`) is built
+// from: the stored value and its partial, the PUT and PATCH wire branches,
+// and the GET response branch (moved from the reference app's
+// `common/schemas/settings.schema.ts` by #736, which re-exports them).
+//
+// THE SECRET ACCESS KEY IS NOT HERE, AND MUST NEVER BE ADDED: it lives in the
+// encrypted credential store at `(purpose 'storage', name 'default')`.
+// `StorageSettingsCarriesNoSecret` at the bottom fails to compile the moment a
+// secret-named field is added.
+// =============================================================================
+import { z } from 'zod';
+import { STORAGE_DRIVER_ID_PATTERN } from './constants.js';
+/**
+ * A storage driver id: any string matching {@link STORAGE_DRIVER_ID_PATTERN}.
+ * Not an enum: an app registers drivers (`registerStorageDriver`), and the API
+ * validates the id against the registry.
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export const storageDriverIdSchema = z.string().regex(STORAGE_DRIVER_ID_PATTERN);
+/**
+ * One driver's non-secret settings as stored: whatever that driver's
+ * `settingsSchema` declares. The contract cannot see the registry, so it
+ * checks the shape (a record) and the API validates each entry with the
+ * driver that owns it.
+ *
+ * @stability experimental
+ */
+export const storageDriverSettingsSchema = z.record(z.string(), z.unknown());
+/**
+ * The `drivers` record: driver id to that driver's settings.
+ *
+ * @stability experimental
+ */
+export const storageDriversSchema = z.record(storageDriverIdSchema, storageDriverSettingsSchema);
+/**
+ * The `drivers` record of a PATCH: `null` removes a driver's stored settings
+ * (back to its defaults), an object is merged over them.
+ *
+ * @stability experimental
+ */
+export const storageDriversPatchSchema = z.record(storageDriverIdSchema, storageDriverSettingsSchema.nullable());
+/**
+ * Object-storage configuration (`storage`).
+ *
+ * `provider` is the id of the active driver; `drivers` holds every driver's own
+ * non-secret settings (`drivers.s3.bucket`, `drivers.local-fs.directory`, ...).
+ * "Not configured" is a driver whose settings are incomplete (the built-ins:
+ * `bucket === ''`), never a missing block, exactly as before drivers were
+ * pluggable.
+ *
+ * The six trailing fields are the DEPRECATED FLAT VIEW (`bucket`, `region`,
+ * `endpoint`, `accountId`, `accessKeyId`, `forcePathStyle`): optional here so a
+ * row written by an earlier release still reads (the API's read adapter folds
+ * them into `drivers.<provider>`), and filled on read from the active built-in
+ * driver's settings so existing readers of `GET /api/system-settings` see what
+ * they saw. They are never written by the API; a write stores `provider` and
+ * `drivers` only. Their semantics are the built-in drivers':
+ *
+ *  - `bucket` empty means not configured; `region` empty means not stated (R2
+ *    wants `auto`); `endpoint` empty means "derive it, or use the SDK's host"
+ *    and an explicit value always wins; `accountId` is R2 only;
+ *  - `forcePathStyle` is TRI-STATE, `null` meaning "use this vendor's
+ *    convention" (path style for `s3compatible`, virtual-host for `s3` and
+ *    `r2`).
+ *
+ * NO `.default()` ON ANY FIELD: the defaults live in the namespace declaration
+ * (`STORAGE_SYSTEM_SETTINGS`) and nowhere else.
+ *
+ * NO SECRET, EVER: a driver's secrets are declared by the driver and stored in
+ * the encrypted credential store. `StorageSettingsCarriesNoSecret` below fails
+ * to compile if a secret-named field is added.
+ *
+ * @stability experimental
+ */
+export const systemStorageSchema = z.object({
+    /** The id of the active storage driver (`s3`, `r2`, `s3compatible`, or a registered one). */
+    provider: storageDriverIdSchema,
+    /** Every registered driver's own settings, keyed by driver id. */
+    drivers: storageDriversSchema,
+    /** @deprecated Read view of `drivers.<provider>.bucket` (built-ins). */
+    bucket: z.string().trim().max(255).optional(),
+    /** @deprecated Read view of `drivers.<provider>.region` (built-ins). */
+    region: z.string().trim().max(255).optional(),
+    /** @deprecated Read view of `drivers.<provider>.endpoint` (built-ins). */
+    endpoint: z.string().trim().max(512).optional(),
+    /** @deprecated Read view of `drivers.<provider>.accountId` (built-ins). */
+    accountId: z.string().trim().max(255).optional(),
+    /** @deprecated Read view of `drivers.<provider>.accessKeyId` (built-ins). An identifier, never the secret. */
+    accessKeyId: z.string().trim().max(255).optional(),
+    /** @deprecated Read view of `drivers.<provider>.forcePathStyle` (built-ins). Tri-state. */
+    forcePathStyle: z.boolean().nullable().optional(),
+});
+/**
+ * `storage`, one level deep: the canonical partial. Every field optional; an
+ * empty string in a flat field is a meaningful value (it clears the field), so
+ * the merge uses `??`, and `forcePathStyle` is the one nullable field (absent
+ * leaves it alone, `null` restores the vendor convention).
+ *
+ * @stability experimental
+ */
+export const systemStoragePatchSchema = z.object({
+    /** The id of the active storage driver. */
+    provider: storageDriverIdSchema.optional(),
+    /** Driver settings to merge, per driver id; `null` removes a driver's stored settings. */
+    drivers: storageDriversPatchSchema.optional(),
+    /** Alias of `drivers.<provider>.bucket` (built-ins); empty means not configured. */
+    bucket: z.string().trim().max(255).optional(),
+    /** Alias of `drivers.<provider>.region` (built-ins); `auto` for R2. */
+    region: z.string().trim().max(255).optional(),
+    /** Alias of `drivers.<provider>.endpoint` (built-ins); empty means derive it (R2) or use the SDK's host. */
+    endpoint: z.string().trim().max(512).optional(),
+    /** Alias of `drivers.<provider>.accountId` (built-ins, R2 only). */
+    accountId: z.string().trim().max(255).optional(),
+    /** Alias of `drivers.<provider>.accessKeyId` (built-ins): an identifier, never the secret. */
+    accessKeyId: z.string().trim().max(255).optional(),
+    /**
+     * Alias of `drivers.<provider>.forcePathStyle` (built-ins). `.nullable().optional()`
+     * means two different things, and both are wanted: absent is "leave it alone",
+     * explicit `null` is "go back to this vendor's convention".
+     */
+    forcePathStyle: z.boolean().nullable().optional(),
+});
+// =============================================================================
+// Storage configuration on the wire (#373, epic #372; drivers: PP-14.7)
+// =============================================================================
+//
+// These are the OpenAPI-visible request schemas. Optional in the PUT body like
+// the operations namespaces, and for the identical reason: the block ships
+// ahead of every client that knows it exists.
+//
+// NO `secretAccessKey` FIELD, ON EITHER SCHEMA, EVER. A driver's secrets are
+// written through the credential store, not through this document: accepting
+// one here would put it in the request body of an endpoint whose audit rows
+// record the full merged value, and in the response of the GET that follows.
+/**
+ * The `storage` branch of the `PUT /api/system-settings` body (no secret, ever).
+ * Send `provider` and `drivers`; the six flat fields are accepted as aliases of
+ * `drivers.<provider>` for clients written before drivers were pluggable.
+ *
+ * @stability experimental
+ */
+export const storageSettingsSchema = z.object({
+    /** The id of the active storage driver. */
+    provider: storageDriverIdSchema,
+    /** Every driver's own settings, keyed by driver id. */
+    drivers: storageDriversSchema.optional(),
+    /** Alias of `drivers.<provider>.bucket` (built-ins); empty means not configured. */
+    bucket: z.string().trim().max(255).optional(),
+    /** Alias of `drivers.<provider>.region` (built-ins); `auto` for R2. */
+    region: z.string().trim().max(255).optional(),
+    /** Alias of `drivers.<provider>.endpoint` (built-ins); empty means derive it (R2) or use the SDK's host. */
+    endpoint: z.string().trim().max(512).optional(),
+    /** Alias of `drivers.<provider>.accountId` (built-ins, R2 only). */
+    accountId: z.string().trim().max(255).optional(),
+    /** Alias of `drivers.<provider>.accessKeyId` (built-ins): an identifier, never the secret. */
+    accessKeyId: z.string().trim().max(255).optional(),
+    /** Alias of `drivers.<provider>.forcePathStyle` (built-ins); tri-state, `null` is "use this vendor's convention". */
+    forcePathStyle: z.boolean().nullable().optional(),
+});
+// THE LINE THAT MAKES A STORAGE PATCH DO ANYTHING AT ALL. Without it
+// `PATCH { "storage": { "bucket": "my-bucket" } }` parses to `{}` in the global
+// ZodValidationPipe and the endpoint answers 200 with the row rewritten
+// unchanged. `common/schemas/settings-parity.spec.ts` fails the build if it is
+// ever dropped.
+/**
+ * The `storage` branch of the `PATCH /api/system-settings` body; `''` clears a field, absent leaves it.
+ *
+ * @stability experimental
+ */
+export const storageSettingsPatchSchema = systemStoragePatchSchema;
+/**
+ * The `storage` branch of the `GET /api/system-settings` response (no secret,
+ * ever). `provider` and `drivers` are the stored shape; the six flat fields are
+ * the deprecated read view of the active built-in driver (empty strings and
+ * `null` when the active driver is not a built-in).
+ *
+ * @stability experimental
+ */
+export const storageResponseSchema = z.object({
+    /** The id of the active storage driver. */
+    provider: storageDriverIdSchema,
+    /** Every registered driver's own settings, keyed by driver id (defaults filled). */
+    drivers: storageDriversSchema,
+    /** @deprecated Read view of `drivers.<provider>.bucket`; empty means not configured. */
+    bucket: z.string(),
+    /** @deprecated Read view of `drivers.<provider>.region`. */
+    region: z.string(),
+    /** @deprecated Read view of `drivers.<provider>.endpoint`. */
+    endpoint: z.string(),
+    /** @deprecated Read view of `drivers.<provider>.accountId`. */
+    accountId: z.string(),
+    /** @deprecated Read view of `drivers.<provider>.accessKeyId`: an identifier, never the secret. */
+    accessKeyId: z.string(),
+    /**
+     * @deprecated Read view of `drivers.<provider>.forcePathStyle`. Tri-state, and
+     * `null` is published as `null` rather than coerced to `false`.
+     */
+    forcePathStyle: z.boolean().nullable(),
+});
+/**
+ * The value that makes {@link StorageSettingsCarriesNoSecret} a compile-time check.
+ *
+ * @stability stable
+ */
+export const STORAGE_SETTINGS_CARRIES_NO_SECRET = true;
+//# sourceMappingURL=settings-schemas.js.map

package/dist/esm/storage/settings-schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-schemas.js","sourceRoot":"","sources":["../../../src/storage/settings-schemas.ts"],"names":[],"mappings":"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"}

package/dist/esm/storage/storage-bucket-provision.d.ts

@@ -0,0 +1,152 @@
+import { z } from 'zod';
+import { type StorageEnum } from './constants.js';
+/**
+ * The configuration whose bucket to create — the SUBMITTED, UNSAVED one, for
+ * the same reason the connection test takes one: an operator provisions the new
+ * bucket before pointing the deployment at it, not after.
+ *
+ * Reuses the test request's schema rather than restating it. No `confirmation`:
+ * creating a bucket strands nothing, and a bucket that already exists is
+ * reported as `already_exists` rather than touched.
+ *
+ * @stability experimental
+ */
+export declare const provisionStorageBucketSchema: z.ZodObject<{
+    secretAccessKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    provider: z.ZodString;
+    bucket: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+    accessKeyId: z.ZodOptional<z.ZodString>;
+    secrets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodNullable<z.ZodString>>>>>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    accountId: z.ZodOptional<z.ZodString>;
+    forcePathStyle: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    drivers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+}, z.core.$strip>;
+/**
+ * The bucket-provisioning body, parsed.
+ *
+ * @stability experimental
+ */
+export type ProvisionStorageBucketInput = z.output<typeof provisionStorageBucketSchema>;
+/**
+ * The four steps, in the order they are attempted.
+ *
+ * `publicAccessBlock` and `encryption` are **AWS S3 only** and are reported as
+ * `skipped` for `r2` and `s3compatible`. That is not laziness: R2 buckets are
+ * private by default and encrypted at rest by default, and `PutPublicAccessBlock`
+ * /`PutBucketEncryption` are AWS-specific APIs that an S3-compatible server is
+ * free not to implement. Calling them anyway would turn "this vendor does not
+ * have that API" into a failed step on a bucket that is already in the state the
+ * step wanted.
+ *
+ * `cors` runs for every provider: it is the one step whose absence breaks the
+ * product rather than loosening it, and every S3-compatible implementation this
+ * application supports has `PutBucketCors`.
+ *
+ * @stability experimental
+ */
+export declare const STORAGE_BUCKET_STEP_IDS: readonly ["create", "publicAccessBlock", "encryption", "cors"];
+/**
+ * One bucket-provisioning step id.
+ *
+ * @stability experimental
+ */
+export type StorageBucketStepId = (typeof STORAGE_BUCKET_STEP_IDS)[number];
+/**
+ * `skipped` covers two different, both-honest cases, and the step's `detail`
+ * says which: the step does not apply to this provider, or an earlier step
+ * failed so hard that attempting it would be meaningless.
+ *
+ * @stability experimental
+ */
+export declare const STORAGE_BUCKET_STEP_STATUSES: readonly ["passed", "failed", "skipped"];
+/**
+ * Five outcomes, and none of them is an HTTP error. See this file's header.
+ *
+ * `created`        every applicable step succeeded, and the bucket is new.
+ * `already_exists` the bucket was already there and owned by this key; the
+ *                  hardening steps still ran, and every applicable one passed.
+ * `partial`        the bucket exists now, but at least one hardening step
+ *                  failed. `steps` says which, and it is the operator's to
+ *                  finish.
+ * `guided`         the credential may not create buckets. `guidance` carries
+ *                  the commands that do it elsewhere. ⚠ NOT AN ERROR.
+ * `failed`         the bucket does not exist and this is not a permissions
+ *                  question — the name is taken by another account, the
+ *                  endpoint is unreachable, the credential is wrong.
+ *
+ * @stability experimental
+ */
+export declare const STORAGE_BUCKET_OUTCOMES: readonly ["created", "already_exists", "partial", "guided", "failed"];
+/**
+ * One bucket-provisioning outcome.
+ *
+ * @stability experimental
+ */
+export type StorageBucketOutcome = (typeof STORAGE_BUCKET_OUTCOMES)[number];
+/**
+ * One step of bucket provisioning and how it went.
+ *
+ * @stability experimental
+ */
+export declare const storageBucketStepSchema: z.ZodObject<{
+    id: z.ZodEnum<StorageEnum<readonly ["create", "publicAccessBlock", "encryption", "cors"]>>;
+    label: z.ZodString;
+    status: z.ZodEnum<StorageEnum<readonly ["passed", "failed", "skipped"]>>;
+    detail: z.ZodString;
+    error: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The ready-to-paste answer the `guided` outcome exists to deliver. Same three
+ * fields, same meanings, as `guidedJobRoleInstructionsSchema` in
+ * `db-backup/dto/db-backup-node-credential.dto.ts` — a second shape for
+ * "here is what to run instead" would be a second thing to render.
+ *
+ * @stability experimental
+ */
+export declare const guidedBucketInstructionsSchema: z.ZodObject<{
+    reason: z.ZodString;
+    commands: z.ZodString;
+    runbook: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The `POST /api/admin/storage-config/bucket` payload, always HTTP 200: read `outcome`.
+ *
+ * @stability experimental
+ */
+export declare const storageBucketProvisionResultSchema: z.ZodObject<{
+    outcome: z.ZodEnum<StorageEnum<readonly ["created", "already_exists", "partial", "guided", "failed"]>>;
+    provider: z.ZodString;
+    bucket: z.ZodString;
+    region: z.ZodString;
+    effectiveEndpoint: z.ZodNullable<z.ZodString>;
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodEnum<StorageEnum<readonly ["create", "publicAccessBlock", "encryption", "cors"]>>;
+        label: z.ZodString;
+        status: z.ZodEnum<StorageEnum<readonly ["passed", "failed", "skipped"]>>;
+        detail: z.ZodString;
+        error: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    message: z.ZodOptional<z.ZodString>;
+    guidance: z.ZodNullable<z.ZodObject<{
+        reason: z.ZodString;
+        commands: z.ZodString;
+        runbook: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    corsOrigin: z.ZodNullable<z.ZodString>;
+    attemptedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+/**
+ * One provisioning step, inferred.
+ *
+ * @stability experimental
+ */
+export type StorageBucketStep = z.infer<typeof storageBucketStepSchema>;
+/**
+ * The provisioning payload, inferred.
+ *
+ * @stability experimental
+ */
+export type StorageBucketProvisionResult = z.infer<typeof storageBucketProvisionResultSchema>;
+//# sourceMappingURL=storage-bucket-provision.d.ts.map

package/dist/esm/storage/storage-bucket-provision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-bucket-provision.d.ts","sourceRoot":"","sources":["../../../src/storage/storage-bucket-provision.ts"],"names":[],"mappings":"AAkDA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAQlD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;iBAA0B,CAAC;AAEpE;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAMxF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,gEAK1B,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,0CAA2C,CAAC;AAErF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,uEAM1B,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;;;;;;iBAWlC,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B;;;;iBA0BzC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;iBAqC7C,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE;;;;GAIG;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,kCAAkC,CAC1C,CAAC"}