@lokalise/connector-api-contracts 1.16.2 → 1.16.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/dist/contracts/authContracts.d.ts +4 -4
  2. package/dist/contracts/authContracts.js +9 -6
  3. package/dist/contracts/authContracts.js.map +1 -1
  4. package/dist/contracts/envContracts.d.ts +0 -17
  5. package/dist/contracts/envContracts.js +0 -5
  6. package/dist/contracts/envContracts.js.map +1 -1
  7. package/dist/contracts/itemGroupContracts.d.ts +98 -0
  8. package/dist/contracts/itemGroupContracts.js +98 -0
  9. package/dist/contracts/itemGroupContracts.js.map +1 -1
  10. package/package.json +1 -1
package/dist/contracts/authContracts.d.ts CHANGED
@@ -25,19 +25,19 @@ export declare const getAuthContract: import("@lokalise/api-contracts").GetRoute
25
25
  }>;
26
26
  }, z.core.$strip>;
27
27
  }>;
28
- export declare const postAuthRequestBody: z.ZodOptional<z.ZodObject<{
28
+ export declare const postAuthRequestBody: z.ZodUnion<readonly [z.ZodObject<{
29
29
  redirectUrl: z.ZodString;
30
30
  state: z.ZodOptional<z.ZodString>;
31
- }, z.core.$strip>>;
31
+ }, z.core.$strip>, z.ZodOptional<z.ZodNull>]>;
32
32
  export type PostAuthRequestBody = z.infer<typeof postAuthRequestBody>;
33
33
  export declare const postAuthResponseBody: z.ZodObject<{}, z.core.$loose>;
34
34
  export type PostAuthResponseBody = Record<string, unknown> & {
35
35
  url?: string;
36
36
  };
37
- export declare const postAuthContract: import("@lokalise/api-contracts").PayloadRouteDefinition<z.ZodOptional<z.ZodObject<{
37
+ export declare const postAuthContract: import("@lokalise/api-contracts").PayloadRouteDefinition<z.ZodUnion<readonly [z.ZodObject<{
38
38
  redirectUrl: z.ZodString;
39
39
  state: z.ZodOptional<z.ZodString>;
40
- }, z.core.$strip>>, z.ZodObject<{}, z.core.$loose>, undefined, undefined, z.ZodObject<{
40
+ }, z.core.$strip>, z.ZodOptional<z.ZodNull>]>, z.ZodObject<{}, z.core.$loose>, undefined, undefined, z.ZodObject<{
41
41
  'ce-config': z.ZodString;
42
42
  "x-connector-id": z.ZodString;
43
43
  }, z.core.$strip>, undefined, false, false, {
package/dist/contracts/authContracts.js CHANGED
@@ -19,12 +19,15 @@ export const getAuthContract = buildGetRoute({
19
19
  requestHeaderSchema: CONNECTOR_REQUEST_HEADERS_SCHEMA_PRE_SETUP,
20
20
  });
21
21
  // postAuth
22
- export const postAuthRequestBody = z
23
- .object({
24
- redirectUrl: z.string(),
25
- state: z.string().optional(),
26
- })
27
- .optional();
22
+ export const postAuthRequestBody = z.union([
23
+ z
24
+ .object({
25
+ redirectUrl: z.string(),
26
+ state: z.string().optional(),
27
+ })
28
+ .describe('For OAuth type'),
29
+ z.null().optional().describe('For apiToken type'),
30
+ ]);
28
31
  export const postAuthResponseBody = z.looseObject({});
29
32
  export const postAuthContract = buildPayloadRoute({
30
33
  method: 'post',
package/dist/contracts/authContracts.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"authContracts.js","sourceRoot":"","sources":["../../src/contracts/authContracts.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"authContracts.js","sourceRoot":"","sources":["../../src/contracts/authContracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC1E,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAC1B,OAAO,EACL,QAAQ,EACR,SAAS,EACT,gCAAgC,EAChC,0CAA0C,GAC3C,MAAM,oBAAoB,CAAA;AAE3B,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,UAAU,CAAU,CAAA;AAE3D,UAAU;AAEV,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC;CACnC,CAAC,CAAA;AAGF;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAC;IAC3C,YAAY,EAAE,GAAG,EAAE,CAAC,OAAO;IAC3B,WAAW,EAAE,gDAAgD;IAC7D,yBAAyB,EAAE,mBAAmB;IAC9C,2BAA2B,EAAE;QAC3B,GAAG,EAAE,mBAAmB;KACzB;IACD,mBAAmB,EAAE,0CAA0C;CAChE,CAAC,CAAA;AAEF,WAAW;AAEX,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC;IACzC,CAAC;SACE,MAAM,CAAC;QACN,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;QACvB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC7B,CAAC;SACD,QAAQ,CAAC,gBAAgB,CAAC;IAC7B,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC;CAClD,CAAC,CAAA;AAGF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC,CAAA;AAIrD,MAAM,CAAC,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;IAChD,MAAM,EAAE,MAAM;IACd,iBAAiB,EAAE,mBAAmB;IACtC,YAAY,EAAE,GAAG,EAAE,CAAC,OAAO;IAC3B,WAAW,EACT,8HAA8H;IAChI,yBAAyB,EAAE,oBAAoB;IAC/C,2BAA2B,EAAE;QAC3B,GAAG,EAAE,oBAAoB;QACzB,GAAG,EAAE,QAAQ;KACd;IACD,mBAAmB,EAAE,0CAA0C;CAChE,CAAC,CAAA;AAEF,kBAAkB;AAElB,MAAM,CAAC,MAAM,uBAAuB,GAAG,iBAAiB,CAAC;IACvD,MAAM,EAAE,MAAM;IACd,iBAAiB,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE;IACtC,YAAY,EAAE,GAAG,EAAE,CAAC,eAAe;IACnC,WAAW,EAAE,8EAA8E;IAC3F,yBAAyB,EAAE,oBAAoB;IAC/C,2BAA2B,EAAE;QAC3B,GAAG,EAAE,oBAAoB;QACzB,GAAG,EAAE,QAAQ;KACd;IACD,mBAAmB,EAAE,gCAAgC;CACtD,CAAC,CAAA;AAEF,mBAAmB;AAEnB,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,KAAK,EAAE,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC;IACxB,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;IAClC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC;CACjC,CAAC,CAAA;AAGF,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC,CAAA;AAG7D,MAAM,CAAC,MAAM,wBAAwB,GAAG,iBAAiB,CAAC;IACxD,MAAM,EAAE,MAAM;IACd,iBAAiB,EAAE,2BAA2B;IAC9C,YAAY,EAAE,GAAG,EAAE,CAAC,gBAAgB;IACpC,WAAW,EAAE,2DAA2D;IACxE,yBAAyB,EAAE,4BAA4B;IACvD,2BAA2B,EAAE;QAC3B,GAAG,EAAE,4BAA4B;QACjC,GAAG,EAAE,SAAS;KACf;IACD,mBAAmB,EAAE,0CAA0C;CAChE,CAAC,CAAA"}
package/dist/contracts/envContracts.d.ts CHANGED
@@ -7,11 +7,6 @@ export declare const localeDefinition: z.ZodObject<{
7
7
  }, z.core.$strip>>;
8
8
  supportedContentTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
9
9
  }, z.core.$strip>;
10
- export declare const connectorIntegrationConfig: z.ZodObject<{
11
- itemGroupIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
12
- metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
13
- }, z.core.$strip>;
14
- export type ConnectorIntegrationConfig = z.infer<typeof connectorIntegrationConfig>;
15
10
  export declare const envResponseBody: z.ZodObject<{
16
11
  defaultLocale: z.ZodString;
17
12
  locales: z.ZodArray<z.ZodObject<{
@@ -20,10 +15,6 @@ export declare const envResponseBody: z.ZodObject<{
20
15
  }, z.core.$strip>>;
21
16
  supportedContentTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
22
17
  cacheItemStructure: z.ZodRecord<z.ZodString, z.ZodString>;
23
- integrationConfig: z.ZodOptional<z.ZodObject<{
24
- itemGroupIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
25
- metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
26
- }, z.core.$strip>>;
27
18
  }, z.core.$strip>;
28
19
  export type EnvCacheItemStructure = {
29
20
  id: string;
@@ -40,10 +31,6 @@ export declare const getEnvContract: import("@lokalise/api-contracts").GetRouteD
40
31
  }, z.core.$strip>>;
41
32
  supportedContentTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
42
33
  cacheItemStructure: z.ZodRecord<z.ZodString, z.ZodString>;
43
- integrationConfig: z.ZodOptional<z.ZodObject<{
44
- itemGroupIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
45
- metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
46
- }, z.core.$strip>>;
47
34
  }, z.core.$strip>, undefined, undefined, z.ZodObject<{
48
35
  'ce-config': z.ZodString;
49
36
  'ce-auth': z.ZodString;
@@ -57,10 +44,6 @@ export declare const getEnvContract: import("@lokalise/api-contracts").GetRouteD
57
44
  }, z.core.$strip>>;
58
45
  supportedContentTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
59
46
  cacheItemStructure: z.ZodRecord<z.ZodString, z.ZodString>;
60
- integrationConfig: z.ZodOptional<z.ZodObject<{
61
- itemGroupIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
62
- metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
63
- }, z.core.$strip>>;
64
47
  }, z.core.$strip>;
65
48
  403: z.ZodObject<{
66
49
  statusCode: z.ZodNumber;
package/dist/contracts/envContracts.js CHANGED
@@ -9,13 +9,8 @@ export const localeDefinition = z.object({
9
9
  })),
10
10
  supportedContentTypes: z.array(z.string()).optional(), // domain content types, e. g. "newsletters", "campaigns", "emails" etc
11
11
  });
12
- export const connectorIntegrationConfig = z.object({
13
- itemGroupIds: z.array(z.string()).optional(),
14
- metadata: z.record(z.string(), z.any()).optional(),
15
- });
16
12
  export const envResponseBody = localeDefinition.extend({
17
13
  cacheItemStructure: z.record(z.string(), z.string()),
18
- integrationConfig: connectorIntegrationConfig.optional(),
19
14
  });
20
15
  export const getEnvContract = buildGetRoute({
21
16
  pathResolver: () => `/env`,
package/dist/contracts/envContracts.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"envContracts.js","sourceRoot":"","sources":["../../src/contracts/envContracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAC1B,OAAO,EAAE,4BAA4B,EAAE,gCAAgC,EAAE,MAAM,oBAAoB,CAAA;AAEnG,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,OAAO,EAAE,CAAC,CAAC,KAAK,CACd,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;KACjB,CAAC,CACH;IACD,qBAAqB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,uEAAuE;CAC/H,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC5C,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,EAAE;CACnD,CAAC,CAAA;AAIF,MAAM,CAAC,MAAM,eAAe,GAAG,gBAAgB,CAAC,MAAM,CAAC;IACrD,kBAAkB,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IACpD,iBAAiB,EAAE,0BAA0B,CAAC,QAAQ,EAAE;CACzD,CAAC,CAAA;AAYF,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAC;IAC1C,YAAY,EAAE,GAAG,EAAE,CAAC,MAAM;IAC1B,WAAW,EACT,uIAAuI;IACzI,yBAAyB,EAAE,eAAe;IAC1C,2BAA2B,EAAE;QAC3B,GAAG,EAAE,eAAe;QACpB,GAAG,EAAE,4BAA4B;KAClC;IACD,mBAAmB,EAAE,gCAAgC;CACtD,CAAC,CAAA"}
1
+ {"version":3,"file":"envContracts.js","sourceRoot":"","sources":["../../src/contracts/envContracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAC1B,OAAO,EAAE,4BAA4B,EAAE,gCAAgC,EAAE,MAAM,oBAAoB,CAAA;AAEnG,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,OAAO,EAAE,CAAC,CAAC,KAAK,CACd,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;KACjB,CAAC,CACH;IACD,qBAAqB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,uEAAuE;CAC/H,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,gBAAgB,CAAC,MAAM,CAAC;IACrD,kBAAkB,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;CACrD,CAAC,CAAA;AAYF,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAC;IAC1C,YAAY,EAAE,GAAG,EAAE,CAAC,MAAM;IAC1B,WAAW,EACT,uIAAuI;IACzI,yBAAyB,EAAE,eAAe;IAC1C,2BAA2B,EAAE;QAC3B,GAAG,EAAE,eAAe;QACpB,GAAG,EAAE,4BAA4B;KAClC;IACD,mBAAmB,EAAE,gCAAgC;CACtD,CAAC,CAAA"}
package/dist/contracts/itemGroupContracts.d.ts CHANGED
@@ -1,10 +1,108 @@
1
1
  import { z } from 'zod/v4';
2
+ /**
3
+ * Item Group Contracts
4
+ *
5
+ * This contract provides a generic, hierarchical grouping mechanism that adapters can use
6
+ * to expose organizational structures from third-party systems. The design is intentionally
7
+ * flexible to accommodate various connector-specific concepts.
8
+ *
9
+ * ## Supported Use Cases
10
+ *
11
+ * ### 1. Spaces / Workspaces Selection (e.g., Storyblok spaces, Contentful spaces)
12
+ *
13
+ * For connectors that need to list available spaces/workspaces for user selection:
14
+ *
15
+ * - Call `/v1/item-groups` WITHOUT `parentItemGroupId` to get a flat list of spaces
16
+ * - Each `ItemGroupEntry` represents a space with:
17
+ * - `id`: The space identifier (e.g., Storyblok `space_id`)
18
+ * - `name`: Display name for the UI
19
+ * - `details`: Additional space metadata (e.g., `{ region: "eu", plan: "enterprise" }`)
20
+ * - The selected space ID can then be stored via `PUT /v1/integrations/{integrationId}/config`
21
+ * using `itemGroupIds` or `metadata` fields (see content-type-app-engine-contracts)
22
+ *
23
+ * This supports both:
24
+ * - **Option A**: Adapter exposes spaces list, UI lets user select, stores in config
25
+ * - **Option B**: User manually provides spaceId (no item-groups call needed)
26
+ *
27
+ * ### 2. Folder / Directory Tree Navigation (e.g., Storyblok folders, CMS categories)
28
+ *
29
+ * For connectors that need hierarchical folder/category navigation:
30
+ *
31
+ * - Call `/v1/item-groups` WITHOUT `parentItemGroupId` to get root-level folders
32
+ * - Call `/v1/item-groups?parentItemGroupId=<folderId>` to get children of a specific folder
33
+ * - Each `ItemGroupEntry` represents a folder with:
34
+ * - `id`: Folder identifier
35
+ * - `name`: Folder display name
36
+ * - `parentItemGroupId`: Reference to parent folder (for tree reconstruction)
37
+ * - `details`: Additional folder metadata (e.g., `{ slug: "blog", fullPath: "website/blog", isFolder: true }`)
38
+ *
39
+ * The UI can use this to:
40
+ * - Render a navigable folder tree
41
+ * - Let users select import scope (single or multiple folder roots)
42
+ * - Store selected folder IDs via `PUT /v1/integrations/{integrationId}/config`
43
+ *
44
+ * ### 3. Folder Scope Variants
45
+ *
46
+ * The contract supports multiple folder scoping strategies:
47
+ *
48
+ * - **No folder roots in config**: Start from real root, pass folder path as parameter to calls
49
+ * - **Single root folder**: `itemGroupIds` contains exactly one folder ID
50
+ * - **Multiple root folders**: `itemGroupIds` contains several folder IDs (union of subtrees)
51
+ *
52
+ * The `details` field can store additional scope information like `fullPath` for path-based
53
+ * filtering (e.g., `starts_with` queries).
54
+ *
55
+ * ## Platform UI Integration
56
+ *
57
+ * The Platform UI uses this contract to:
58
+ * 1. Get available spaces for the authenticated user (PAT/OAuth)
59
+ * 2. Get folder structure for chosen space (hierarchical navigation)
60
+ * 3. Allow user to select which parts of the space to sync
61
+ * 4. Store selections via `PUT /v1/integrations/{integrationId}/config` for subsequent import runs
62
+ */
2
63
  export declare const itemGroupListRequestQueryString: z.ZodObject<{
3
64
  limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
4
65
  cursor: z.ZodOptional<z.ZodString>;
5
66
  parentItemGroupId: z.ZodOptional<z.ZodString>;
6
67
  }, z.core.$strip>;
7
68
  export type ItemGroupListRequestQueryString = z.infer<typeof itemGroupListRequestQueryString>;
69
+ /**
70
+ * Represents a single item group entry (space, folder, category, etc.)
71
+ *
72
+ * ## Field Mapping Examples
73
+ *
74
+ * ### For Spaces (Storyblok, Contentful, etc.)
75
+ * ```
76
+ * {
77
+ * id: "12345", // space_id
78
+ * name: "Marketing Site", // space name for UI display
79
+ * parentItemGroupId: null, // spaces are typically root-level
80
+ * details: {
81
+ * region: "eu",
82
+ * plan: "enterprise",
83
+ * createdAt: "2024-01-01"
84
+ * }
85
+ * }
86
+ * ```
87
+ *
88
+ * ### For Folders (hierarchical navigation)
89
+ * ```
90
+ * {
91
+ * id: "folder-789",
92
+ * name: "Blog",
93
+ * parentItemGroupId: "folder-456", // parent folder reference
94
+ * details: {
95
+ * slug: "blog",
96
+ * fullPath: "website/blog", // for path-based filtering
97
+ * isFolder: true, // distinguish from content items
98
+ * isSelectable: true // UI can use to control selection
99
+ * }
100
+ * }
101
+ * ```
102
+ *
103
+ * The `details` field is intentionally flexible to accommodate connector-specific
104
+ * metadata without requiring contract changes.
105
+ */
8
106
  export declare const itemGroupEntry: z.ZodObject<{
9
107
  id: z.ZodString;
10
108
  name: z.ZodString;
package/dist/contracts/itemGroupContracts.js CHANGED
@@ -3,6 +3,67 @@ import { z } from 'zod/v4';
3
3
  import { MAX_TITLE_LENGTH } from "./cacheContracts.js";
4
4
  import { COMMON_ERROR_RESPONSE_SCHEMA, CONNECTOR_REQUEST_HEADERS_SCHEMA } from "./commonSchemas.js";
5
5
  import { PAGINATION_RESPONSE_METADATA_SCHEMA } from "./paginationSchemas.js";
6
+ /**
7
+ * Item Group Contracts
8
+ *
9
+ * This contract provides a generic, hierarchical grouping mechanism that adapters can use
10
+ * to expose organizational structures from third-party systems. The design is intentionally
11
+ * flexible to accommodate various connector-specific concepts.
12
+ *
13
+ * ## Supported Use Cases
14
+ *
15
+ * ### 1. Spaces / Workspaces Selection (e.g., Storyblok spaces, Contentful spaces)
16
+ *
17
+ * For connectors that need to list available spaces/workspaces for user selection:
18
+ *
19
+ * - Call `/v1/item-groups` WITHOUT `parentItemGroupId` to get a flat list of spaces
20
+ * - Each `ItemGroupEntry` represents a space with:
21
+ * - `id`: The space identifier (e.g., Storyblok `space_id`)
22
+ * - `name`: Display name for the UI
23
+ * - `details`: Additional space metadata (e.g., `{ region: "eu", plan: "enterprise" }`)
24
+ * - The selected space ID can then be stored via `PUT /v1/integrations/{integrationId}/config`
25
+ * using `itemGroupIds` or `metadata` fields (see content-type-app-engine-contracts)
26
+ *
27
+ * This supports both:
28
+ * - **Option A**: Adapter exposes spaces list, UI lets user select, stores in config
29
+ * - **Option B**: User manually provides spaceId (no item-groups call needed)
30
+ *
31
+ * ### 2. Folder / Directory Tree Navigation (e.g., Storyblok folders, CMS categories)
32
+ *
33
+ * For connectors that need hierarchical folder/category navigation:
34
+ *
35
+ * - Call `/v1/item-groups` WITHOUT `parentItemGroupId` to get root-level folders
36
+ * - Call `/v1/item-groups?parentItemGroupId=<folderId>` to get children of a specific folder
37
+ * - Each `ItemGroupEntry` represents a folder with:
38
+ * - `id`: Folder identifier
39
+ * - `name`: Folder display name
40
+ * - `parentItemGroupId`: Reference to parent folder (for tree reconstruction)
41
+ * - `details`: Additional folder metadata (e.g., `{ slug: "blog", fullPath: "website/blog", isFolder: true }`)
42
+ *
43
+ * The UI can use this to:
44
+ * - Render a navigable folder tree
45
+ * - Let users select import scope (single or multiple folder roots)
46
+ * - Store selected folder IDs via `PUT /v1/integrations/{integrationId}/config`
47
+ *
48
+ * ### 3. Folder Scope Variants
49
+ *
50
+ * The contract supports multiple folder scoping strategies:
51
+ *
52
+ * - **No folder roots in config**: Start from real root, pass folder path as parameter to calls
53
+ * - **Single root folder**: `itemGroupIds` contains exactly one folder ID
54
+ * - **Multiple root folders**: `itemGroupIds` contains several folder IDs (union of subtrees)
55
+ *
56
+ * The `details` field can store additional scope information like `fullPath` for path-based
57
+ * filtering (e.g., `starts_with` queries).
58
+ *
59
+ * ## Platform UI Integration
60
+ *
61
+ * The Platform UI uses this contract to:
62
+ * 1. Get available spaces for the authenticated user (PAT/OAuth)
63
+ * 2. Get folder structure for chosen space (hierarchical navigation)
64
+ * 3. Allow user to select which parts of the space to sync
65
+ * 4. Store selections via `PUT /v1/integrations/{integrationId}/config` for subsequent import runs
66
+ */
6
67
  export const itemGroupListRequestQueryString = z.object({
7
68
  /**
8
69
  * Maximum number of item groups to return
@@ -17,6 +78,43 @@ export const itemGroupListRequestQueryString = z.object({
17
78
  */
18
79
  parentItemGroupId: z.string().optional(),
19
80
  });
81
+ /**
82
+ * Represents a single item group entry (space, folder, category, etc.)
83
+ *
84
+ * ## Field Mapping Examples
85
+ *
86
+ * ### For Spaces (Storyblok, Contentful, etc.)
87
+ * ```
88
+ * {
89
+ * id: "12345", // space_id
90
+ * name: "Marketing Site", // space name for UI display
91
+ * parentItemGroupId: null, // spaces are typically root-level
92
+ * details: {
93
+ * region: "eu",
94
+ * plan: "enterprise",
95
+ * createdAt: "2024-01-01"
96
+ * }
97
+ * }
98
+ * ```
99
+ *
100
+ * ### For Folders (hierarchical navigation)
101
+ * ```
102
+ * {
103
+ * id: "folder-789",
104
+ * name: "Blog",
105
+ * parentItemGroupId: "folder-456", // parent folder reference
106
+ * details: {
107
+ * slug: "blog",
108
+ * fullPath: "website/blog", // for path-based filtering
109
+ * isFolder: true, // distinguish from content items
110
+ * isSelectable: true // UI can use to control selection
111
+ * }
112
+ * }
113
+ * ```
114
+ *
115
+ * The `details` field is intentionally flexible to accommodate connector-specific
116
+ * metadata without requiring contract changes.
117
+ */
20
118
  export const itemGroupEntry = z.object({
21
119
  id: z.string().describe('Unique item group identifier'),
22
120
  name: z.string().max(MAX_TITLE_LENGTH).describe('Item group display name'),
package/dist/contracts/itemGroupContracts.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"itemGroupContracts.js","sourceRoot":"","sources":["../../src/contracts/itemGroupContracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,EAAE,4BAA4B,EAAE,gCAAgC,EAAE,MAAM,oBAAoB,CAAA;AACnG,OAAO,EAAE,mCAAmC,EAAE,MAAM,wBAAwB,CAAA;AAE5E,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IACtD;;OAEG;IACH,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACpD;;OAEG;IACH,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B;;OAEG;IACH,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACzC,CAAC,CAAA;AAIF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;IACvD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,QAAQ,CAAC,yBAAyB,CAAC;IAC1E,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACxC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC;CACvC,CAAC,CAAA;AAIF,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC;KACvC,MAAM,CAAC;IACN,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC;CAC/B,CAAC;KACD,MAAM,CAAC,mCAAmC,CAAC,KAAK,CAAC,CAAA;AAIpD,MAAM,CAAC,MAAM,wBAAwB,GAAG,aAAa,CAAC;IACpD,YAAY,EAAE,GAAG,EAAE,CAAC,iBAAiB;IACrC,WAAW,EAAE,kEAAkE;IAC/E,kBAAkB,EAAE,+BAA+B;IACnD,yBAAyB,EAAE,yBAAyB;IACpD,2BAA2B,EAAE;QAC3B,GAAG,EAAE,yBAAyB;QAC9B,GAAG,EAAE,4BAA4B;KAClC;IACD,mBAAmB,EAAE,gCAAgC;CACtD,CAAC,CAAA"}
1
+ {"version":3,"file":"itemGroupContracts.js","sourceRoot":"","sources":["../../src/contracts/itemGroupContracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,EAAE,4BAA4B,EAAE,gCAAgC,EAAE,MAAM,oBAAoB,CAAA;AACnG,OAAO,EAAE,mCAAmC,EAAE,MAAM,wBAAwB,CAAA;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IACtD;;OAEG;IACH,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACpD;;OAEG;IACH,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B;;OAEG;IACH,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACzC,CAAC,CAAA;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;IACvD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,QAAQ,CAAC,yBAAyB,CAAC;IAC1E,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACxC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC;CACvC,CAAC,CAAA;AAIF,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC;KACvC,MAAM,CAAC;IACN,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC;CAC/B,CAAC;KACD,MAAM,CAAC,mCAAmC,CAAC,KAAK,CAAC,CAAA;AAIpD,MAAM,CAAC,MAAM,wBAAwB,GAAG,aAAa,CAAC;IACpD,YAAY,EAAE,GAAG,EAAE,CAAC,iBAAiB;IACrC,WAAW,EAAE,kEAAkE;IAC/E,kBAAkB,EAAE,+BAA+B;IACnD,yBAAyB,EAAE,yBAAyB;IACpD,2BAA2B,EAAE;QAC3B,GAAG,EAAE,yBAAyB;QAC9B,GAAG,EAAE,4BAA4B;KAClC;IACD,mBAAmB,EAAE,gCAAgC;CACtD,CAAC,CAAA"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lokalise/connector-api-contracts",
3
- "version": "1.16.2",
3
+ "version": "1.16.4",
4
4
  "description": "Lokalise Connector API schemas and contracts",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",