@keboola/api-client 49.0.0 → 51.0.0

package/dist/domain/storageTable/index.d.cts

@@ -1,2 +1,189 @@
-import { C as TableId, S as Table, T as TableName, _ as BucketStage, a as CreateTableFn, b as ParsedBucket, c as COLUMN_NAME_CHARSET_HINT, d as validateStorageName, f as STORAGE_COLUMN_NAME, g as BucketName, h as BucketId, i as CreateBucketFn, l as NAME_CHARSET_HINT, m as Bucket, n as StorageTableInstance, o as TableModel, p as STORAGE_NAME, r as createStorageTable, s as createTableModel, t as StorageTable, u as validateStorageColumnName, v as LegacyBucket, w as TableIdParts, x as StorageBranchBucket, y as ModelOptions } from "../../index-fMoM8SeH.cjs";
-export { Bucket, BucketId, BucketName, BucketStage, COLUMN_NAME_CHARSET_HINT, CreateBucketFn, CreateTableFn, LegacyBucket, ModelOptions, NAME_CHARSET_HINT, ParsedBucket, STORAGE_COLUMN_NAME, STORAGE_NAME, StorageBranchBucket, type StorageTableInstance as StorageTable, type StorageTable as StorageTableScope, Table, TableId, TableIdParts, TableModel, TableName, createStorageTable, createTableModel, validateStorageColumnName, validateStorageName };
+type BucketStage = 'in' | 'out';
+type BucketName = string;
+type TableName = string;
+type BucketId = `${BucketStage}.${BucketName}`;
+type TableId = `${BucketId}.${TableName}`;
+type TableIdParts = [stage: BucketStage, bucket: BucketName, table: TableName];
+type StorageBranchBucket = {
+  kind: 'storage-branch';
+  /** Bare name, no `c-` or `{branchId}-` (branches are BE-side). On-disk: `c-{baseName}` when prefixed. */
+  baseName: BucketName;
+  hasLegacyPrefix: boolean;
+};
+type LegacyBucket = {
+  kind: 'legacy';
+  /**
+   * Bare name, no `c-` or `{branchId}-`. User-facing: `{branchId}-{baseName}`.
+   * On-disk: `c-{branchId}-{baseName}` when prefixed.
+   */
+  baseName: BucketName;
+  hasLegacyPrefix: boolean;
+  /** Dev-branch id encoded into the on-disk name, if any. */
+  branchId: string | null;
+};
+type ParsedBucket = StorageBranchBucket | LegacyBucket;
+type Bucket = ParsedBucket & {
+  stage: BucketStage;
+};
+type Table = {
+  name: TableName;
+  bucket: Bucket;
+};
+type ModelOptions = {
+  /** Project uses the legacy `c-` bucket prefix. (`!ProjectFeature.DisableLegacyBucketPrefix`) */
+  useLegacyBucketPrefix: boolean;
+  /** `ProjectFeature.SoxProtectedDefaultBranch` */
+  hasProtectedDefaultBranch: boolean;
+  /** `ProjectFeature.StorageBranches` */
+  hasStorageBranches: boolean;
+};
+/**
+ * The name of a bucket or a table.
+ *
+ * - Allowed characters: `A-Z`, `a-z`, `0-9`, dash `-` and underscore `_`. Anything else — a
+ *   space, a dot, an accented letter — is rejected, not transliterated.
+ * - 1 to 96 characters.
+ * - Cannot start with an underscore. A dash or a digit as the first character is fine.
+ * - Registered (external) buckets follow this same rule, dashes included.
+ * - Uniqueness is case-insensitive within a stage: creating `MyBucket` next to `mybucket`
+ *   fails with `storage.buckets.alreadyExists`, and for tables with
+ *   `storage.buckets.tableAlreadyExists` or `storage.validation.tableAlreadyExists`.
+ * - To turn arbitrary user input into a name that satisfies this rule, call
+ *   `POST /v2/storage/webalize/display-name` instead of reimplementing the transformation. It
+ *   unaccents the input, replaces every run of disallowed characters with a single `-`, trims
+ *   `-` from both ends, strips leading underscores, and truncates to 96 characters.
+ */
+declare const STORAGE_NAME: {
+  readonly pattern: RegExp;
+  readonly minLength: 1;
+  readonly maxLength: 96;
+};
+/**
+ * The name of a table column.
+ *
+ * - Allowed characters: `A-Z`, `a-z`, `0-9` and underscore `_`. Unlike a bucket or table name,
+ *   a column name may **not** contain a dash.
+ * - 1 to 64 characters.
+ * - Must start with a letter or a digit.
+ * - To turn arbitrary user input into a name that satisfies this rule, call
+ *   `POST /v2/storage/webalize/column-names` instead of reimplementing the transformation. In
+ *   order, it strips emoji, transliterates the rest to ASCII, replaces every run of disallowed
+ *   characters with a single `_`, trims `_` from both ends, truncates to 64 characters, and
+ *   strips any leading `_` the truncation left behind. Input with no usable character left
+ *   webalizes to an empty string, which is *not* a valid column name.
+ * - `POST /v2/storage/validate/column-names` applies one rule the creation endpoints do not:
+ *   it also rejects the backend system columns `oid`, `tableoid`, `xmin`, `cmin`, `xmax`,
+ *   `cmax` and `ctid`.
+ */
+declare const STORAGE_COLUMN_NAME: {
+  readonly pattern: RegExp;
+  readonly minLength: 1;
+  readonly maxLength: 64;
+};
+/**
+ * The charset half of each rule, as a sentence.
+ *
+ * - The generated components carry the rule as a regex; a person filling in a field needs words.
+ * - A bucket or table name admits a dash. A column name does not.
+ */
+declare const NAME_CHARSET_HINT = "Only alphanumeric characters, dashes, and underscores are allowed.";
+declare const COLUMN_NAME_CHARSET_HINT = "Only alphanumeric characters and underscores are allowed.";
+/**
+ * Why Storage would reject `value` as a bucket or table name, or `null` when it would accept it.
+ *
+ * - Checks the published `StorageName` component — charset, length and the leading underscore.
+ * - Knows nothing about names already taken; uniqueness is the caller's own lookup.
+ * - `entity` only names the thing in the message.
+ */
+declare const validateStorageName: (value: string, entity?: string) => string | null;
+/**
+ * Why Storage would reject `value` as a column name, or `null` when it would accept it.
+ *
+ * - Checks the published `StorageColumnName` component, which is a different, stricter rule than
+ *   `validateStorageName`: no dash, 64 characters, and the first character must be alphanumeric.
+ * - `POST /v2/storage/validate/column-names` additionally rejects the backend system columns; that
+ *   is a server round-trip, not part of this check.
+ */
+declare const validateStorageColumnName: (value: string, entity?: string) => string | null;
+type CreateBucketFn = (input: {
+  stage: BucketStage;
+  name: BucketName;
+  branchId?: string | null;
+}) => Bucket;
+type CreateTableFn = (input: {
+  stage: BucketStage;
+  tableName: TableName;
+  bucketName: BucketName;
+  branchId?: string | null;
+}) => Table;
+type TableModel = {
+  parse(id: string): Table;
+  parseBucket(id: string): Bucket;
+  safeParse(id: string): Table | null;
+  safeParseBucket(id: string): Bucket | null;
+  serializeTableId(table: Table): TableId;
+  serializeBucketId(bucket: Bucket): BucketId;
+  serializeBucketName(bucket: Bucket): BucketName;
+  serializeBucketDisplayName(bucket: Bucket): BucketName;
+  safeSerializeTableId(table: Table): TableId | null;
+  safeSerializeBucketId(bucket: Bucket): BucketId | null;
+  safeSerializeBucketName(bucket: Bucket): BucketName | null;
+  createTable: CreateTableFn;
+  createBucket: CreateBucketFn;
+};
+declare const createTableModel: (options: ModelOptions) => TableModel;
+type StorageTableInstance = {
+  readonly bucket: Bucket;
+  readonly name: TableName | null;
+  isInBranch(branchId: string): boolean;
+  addBranch(branchId: string): StorageTableInstance;
+  removeBranch(branchId: string): StorageTableInstance;
+  /** A new instance with the table name set (or replaced). */
+  addTableName(tableName: TableName): StorageTableInstance;
+  getBucketName(): BucketName;
+  /** Bucket name as shown to users: dev-branch prefix kept, legacy `c-` prefix always dropped. */
+  getBucketDisplayName(): BucketName;
+  /** Bare bucket name: no `c-` prefix, no dev-branch prefix (legacy `baseName`, or the canonical storage-branch name). */
+  getBucketBaseName(): BucketName;
+  getBucketId(): BucketId;
+  getSafeBucketId(): BucketId | null;
+  /** @throws when there is no table name (the instance was built via `createBucket`). */
+  getTableName(): TableName;
+  /** @throws when there is no table name (the instance was built via `createBucket`). */
+  getTableId(): TableId;
+  /** Null when there is no table name (built via `createBucket`) or a segment is empty. */
+  getSafeTableId(): TableId | null;
+};
+type StorageTable = {
+  parse(id: string): StorageTableInstance;
+  safeParse(id: string): StorageTableInstance | null;
+  /** Decode a bucket id (`{stage}.{bucket}`) into a bucket-only instance. */
+  parseBucket(id: string): StorageTableInstance;
+  safeParseBucket(id: string): StorageTableInstance | null;
+  createTable(input: Parameters<CreateTableFn>[0]): StorageTableInstance;
+  createBucket(input: Parameters<CreateBucketFn>[0]): StorageTableInstance;
+  createDefaultBucket(input: {
+    stage: BucketStage;
+    name: string;
+  }): StorageTableInstance;
+  /** Like `createDefaultBucket`, but returns null instead of throwing when the name sanitizes to an empty/invalid segment. */
+  safeCreateDefaultBucket(input: {
+    stage: BucketStage;
+    name: string;
+  }): StorageTableInstance | null;
+  createDefaultConfigBucket(input: {
+    stage: BucketStage;
+    componentId: string;
+    configId: string;
+  }): StorageTableInstance;
+  createDefaultConfigTable(input: {
+    stage: BucketStage;
+    componentId: string;
+    configId: string;
+    tableName: string;
+  }): StorageTableInstance;
+  createDefaultCsvImportTable(configId: string): StorageTableInstance;
+};
+declare const createStorageTable: (flags: ModelOptions) => StorageTable;
+export { Bucket, BucketId, BucketName, BucketStage, COLUMN_NAME_CHARSET_HINT, CreateBucketFn, CreateTableFn, LegacyBucket, ModelOptions, NAME_CHARSET_HINT, ParsedBucket, STORAGE_COLUMN_NAME, STORAGE_NAME, StorageBranchBucket, type StorageTableInstance as StorageTable, type StorageTable as StorageTableScope, Table, TableId, TableIdParts, TableModel, TableName, createStorageTable, createTableModel, validateStorageColumnName, validateStorageName };
+//# sourceMappingURL=index.d.cts.map

package/dist/domain/storageTable/index.d.ts

@@ -1,2 +1,189 @@
-import { C as TableId, S as Table, T as TableName, _ as BucketStage, a as CreateTableFn, b as ParsedBucket, c as COLUMN_NAME_CHARSET_HINT, d as validateStorageName, f as STORAGE_COLUMN_NAME, g as BucketName, h as BucketId, i as CreateBucketFn, l as NAME_CHARSET_HINT, m as Bucket, n as StorageTableInstance, o as TableModel, p as STORAGE_NAME, r as createStorageTable, s as createTableModel, t as StorageTable, u as validateStorageColumnName, v as LegacyBucket, w as TableIdParts, x as StorageBranchBucket, y as ModelOptions } from "../../index-fMoM8SeH.js";
-export { Bucket, BucketId, BucketName, BucketStage, COLUMN_NAME_CHARSET_HINT, CreateBucketFn, CreateTableFn, LegacyBucket, ModelOptions, NAME_CHARSET_HINT, ParsedBucket, STORAGE_COLUMN_NAME, STORAGE_NAME, StorageBranchBucket, type StorageTableInstance as StorageTable, type StorageTable as StorageTableScope, Table, TableId, TableIdParts, TableModel, TableName, createStorageTable, createTableModel, validateStorageColumnName, validateStorageName };
+type BucketStage = 'in' | 'out';
+type BucketName = string;
+type TableName = string;
+type BucketId = `${BucketStage}.${BucketName}`;
+type TableId = `${BucketId}.${TableName}`;
+type TableIdParts = [stage: BucketStage, bucket: BucketName, table: TableName];
+type StorageBranchBucket = {
+  kind: 'storage-branch';
+  /** Bare name, no `c-` or `{branchId}-` (branches are BE-side). On-disk: `c-{baseName}` when prefixed. */
+  baseName: BucketName;
+  hasLegacyPrefix: boolean;
+};
+type LegacyBucket = {
+  kind: 'legacy';
+  /**
+   * Bare name, no `c-` or `{branchId}-`. User-facing: `{branchId}-{baseName}`.
+   * On-disk: `c-{branchId}-{baseName}` when prefixed.
+   */
+  baseName: BucketName;
+  hasLegacyPrefix: boolean;
+  /** Dev-branch id encoded into the on-disk name, if any. */
+  branchId: string | null;
+};
+type ParsedBucket = StorageBranchBucket | LegacyBucket;
+type Bucket = ParsedBucket & {
+  stage: BucketStage;
+};
+type Table = {
+  name: TableName;
+  bucket: Bucket;
+};
+type ModelOptions = {
+  /** Project uses the legacy `c-` bucket prefix. (`!ProjectFeature.DisableLegacyBucketPrefix`) */
+  useLegacyBucketPrefix: boolean;
+  /** `ProjectFeature.SoxProtectedDefaultBranch` */
+  hasProtectedDefaultBranch: boolean;
+  /** `ProjectFeature.StorageBranches` */
+  hasStorageBranches: boolean;
+};
+/**
+ * The name of a bucket or a table.
+ *
+ * - Allowed characters: `A-Z`, `a-z`, `0-9`, dash `-` and underscore `_`. Anything else — a
+ *   space, a dot, an accented letter — is rejected, not transliterated.
+ * - 1 to 96 characters.
+ * - Cannot start with an underscore. A dash or a digit as the first character is fine.
+ * - Registered (external) buckets follow this same rule, dashes included.
+ * - Uniqueness is case-insensitive within a stage: creating `MyBucket` next to `mybucket`
+ *   fails with `storage.buckets.alreadyExists`, and for tables with
+ *   `storage.buckets.tableAlreadyExists` or `storage.validation.tableAlreadyExists`.
+ * - To turn arbitrary user input into a name that satisfies this rule, call
+ *   `POST /v2/storage/webalize/display-name` instead of reimplementing the transformation. It
+ *   unaccents the input, replaces every run of disallowed characters with a single `-`, trims
+ *   `-` from both ends, strips leading underscores, and truncates to 96 characters.
+ */
+declare const STORAGE_NAME: {
+  readonly pattern: RegExp;
+  readonly minLength: 1;
+  readonly maxLength: 96;
+};
+/**
+ * The name of a table column.
+ *
+ * - Allowed characters: `A-Z`, `a-z`, `0-9` and underscore `_`. Unlike a bucket or table name,
+ *   a column name may **not** contain a dash.
+ * - 1 to 64 characters.
+ * - Must start with a letter or a digit.
+ * - To turn arbitrary user input into a name that satisfies this rule, call
+ *   `POST /v2/storage/webalize/column-names` instead of reimplementing the transformation. In
+ *   order, it strips emoji, transliterates the rest to ASCII, replaces every run of disallowed
+ *   characters with a single `_`, trims `_` from both ends, truncates to 64 characters, and
+ *   strips any leading `_` the truncation left behind. Input with no usable character left
+ *   webalizes to an empty string, which is *not* a valid column name.
+ * - `POST /v2/storage/validate/column-names` applies one rule the creation endpoints do not:
+ *   it also rejects the backend system columns `oid`, `tableoid`, `xmin`, `cmin`, `xmax`,
+ *   `cmax` and `ctid`.
+ */
+declare const STORAGE_COLUMN_NAME: {
+  readonly pattern: RegExp;
+  readonly minLength: 1;
+  readonly maxLength: 64;
+};
+/**
+ * The charset half of each rule, as a sentence.
+ *
+ * - The generated components carry the rule as a regex; a person filling in a field needs words.
+ * - A bucket or table name admits a dash. A column name does not.
+ */
+declare const NAME_CHARSET_HINT = "Only alphanumeric characters, dashes, and underscores are allowed.";
+declare const COLUMN_NAME_CHARSET_HINT = "Only alphanumeric characters and underscores are allowed.";
+/**
+ * Why Storage would reject `value` as a bucket or table name, or `null` when it would accept it.
+ *
+ * - Checks the published `StorageName` component — charset, length and the leading underscore.
+ * - Knows nothing about names already taken; uniqueness is the caller's own lookup.
+ * - `entity` only names the thing in the message.
+ */
+declare const validateStorageName: (value: string, entity?: string) => string | null;
+/**
+ * Why Storage would reject `value` as a column name, or `null` when it would accept it.
+ *
+ * - Checks the published `StorageColumnName` component, which is a different, stricter rule than
+ *   `validateStorageName`: no dash, 64 characters, and the first character must be alphanumeric.
+ * - `POST /v2/storage/validate/column-names` additionally rejects the backend system columns; that
+ *   is a server round-trip, not part of this check.
+ */
+declare const validateStorageColumnName: (value: string, entity?: string) => string | null;
+type CreateBucketFn = (input: {
+  stage: BucketStage;
+  name: BucketName;
+  branchId?: string | null;
+}) => Bucket;
+type CreateTableFn = (input: {
+  stage: BucketStage;
+  tableName: TableName;
+  bucketName: BucketName;
+  branchId?: string | null;
+}) => Table;
+type TableModel = {
+  parse(id: string): Table;
+  parseBucket(id: string): Bucket;
+  safeParse(id: string): Table | null;
+  safeParseBucket(id: string): Bucket | null;
+  serializeTableId(table: Table): TableId;
+  serializeBucketId(bucket: Bucket): BucketId;
+  serializeBucketName(bucket: Bucket): BucketName;
+  serializeBucketDisplayName(bucket: Bucket): BucketName;
+  safeSerializeTableId(table: Table): TableId | null;
+  safeSerializeBucketId(bucket: Bucket): BucketId | null;
+  safeSerializeBucketName(bucket: Bucket): BucketName | null;
+  createTable: CreateTableFn;
+  createBucket: CreateBucketFn;
+};
+declare const createTableModel: (options: ModelOptions) => TableModel;
+type StorageTableInstance = {
+  readonly bucket: Bucket;
+  readonly name: TableName | null;
+  isInBranch(branchId: string): boolean;
+  addBranch(branchId: string): StorageTableInstance;
+  removeBranch(branchId: string): StorageTableInstance;
+  /** A new instance with the table name set (or replaced). */
+  addTableName(tableName: TableName): StorageTableInstance;
+  getBucketName(): BucketName;
+  /** Bucket name as shown to users: dev-branch prefix kept, legacy `c-` prefix always dropped. */
+  getBucketDisplayName(): BucketName;
+  /** Bare bucket name: no `c-` prefix, no dev-branch prefix (legacy `baseName`, or the canonical storage-branch name). */
+  getBucketBaseName(): BucketName;
+  getBucketId(): BucketId;
+  getSafeBucketId(): BucketId | null;
+  /** @throws when there is no table name (the instance was built via `createBucket`). */
+  getTableName(): TableName;
+  /** @throws when there is no table name (the instance was built via `createBucket`). */
+  getTableId(): TableId;
+  /** Null when there is no table name (built via `createBucket`) or a segment is empty. */
+  getSafeTableId(): TableId | null;
+};
+type StorageTable = {
+  parse(id: string): StorageTableInstance;
+  safeParse(id: string): StorageTableInstance | null;
+  /** Decode a bucket id (`{stage}.{bucket}`) into a bucket-only instance. */
+  parseBucket(id: string): StorageTableInstance;
+  safeParseBucket(id: string): StorageTableInstance | null;
+  createTable(input: Parameters<CreateTableFn>[0]): StorageTableInstance;
+  createBucket(input: Parameters<CreateBucketFn>[0]): StorageTableInstance;
+  createDefaultBucket(input: {
+    stage: BucketStage;
+    name: string;
+  }): StorageTableInstance;
+  /** Like `createDefaultBucket`, but returns null instead of throwing when the name sanitizes to an empty/invalid segment. */
+  safeCreateDefaultBucket(input: {
+    stage: BucketStage;
+    name: string;
+  }): StorageTableInstance | null;
+  createDefaultConfigBucket(input: {
+    stage: BucketStage;
+    componentId: string;
+    configId: string;
+  }): StorageTableInstance;
+  createDefaultConfigTable(input: {
+    stage: BucketStage;
+    componentId: string;
+    configId: string;
+    tableName: string;
+  }): StorageTableInstance;
+  createDefaultCsvImportTable(configId: string): StorageTableInstance;
+};
+declare const createStorageTable: (flags: ModelOptions) => StorageTable;
+export { Bucket, BucketId, BucketName, BucketStage, COLUMN_NAME_CHARSET_HINT, CreateBucketFn, CreateTableFn, LegacyBucket, ModelOptions, NAME_CHARSET_HINT, ParsedBucket, STORAGE_COLUMN_NAME, STORAGE_NAME, StorageBranchBucket, type StorageTableInstance as StorageTable, type StorageTable as StorageTableScope, Table, TableId, TableIdParts, TableModel, TableName, createStorageTable, createTableModel, validateStorageColumnName, validateStorageName };
+//# sourceMappingURL=index.d.ts.map