@contentful/experience-design-system-types 2.38.0 → 2.38.1-dev-build-6d903339.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-types",
-  "version": "2.38.0",
+  "version": "2.38.1-dev-build-6d903339.0",
   "license": "MIT",
   "type": "module",
   "module": "./dist/src/index.js",
@@ -16,6 +16,11 @@
       "types": "./dist/src/config/index.d.ts",
       "import": "./dist/src/config/index.js",
       "node": "./dist/src/config/index.js"
+    },
+    "./handoff": {
+      "types": "./dist/src/handoff/index.d.ts",
+      "import": "./dist/src/handoff/index.js",
+      "node": "./dist/src/handoff/index.js"
     }
   },
   "publishConfig": {

package/dist/src/handoff/index.d.ts

@@ -0,0 +1,72 @@
+import * as z from 'zod/mini';
+export declare const HANDOFF_ENV = "EDS_IMPORT_HANDOFF";
+declare const ImportHandoffSchema: z.ZodMiniObject<{
+    /** The user skipped the credentials screen, so nothing is fetched from or pushed to Contentful. */
+    credentialsSkipped: z.ZodMiniBoolean<boolean>;
+    tokens: z.ZodMiniObject<{
+        /**
+         * What to do about an existing `tokens.json`.
+         * reuse: keep it. regenerate: build it again with the cache off. generate: nothing was asked, build it as usual.
+         */
+        strategy: z.ZodMiniEnum<{
+            reuse: "reuse";
+            regenerate: "regenerate";
+            generate: "generate";
+        }>;
+    }, z.core.$strip>;
+    /** Present once the CLI has run the extraction stage; the wizard then starts at the scope gate. */
+    extraction: z.ZodMiniOptional<z.ZodMiniObject<{
+        sessionId: z.ZodMiniString<string>;
+        outDir: z.ZodMiniString<string>;
+        tokensPath: z.ZodMiniString<string>;
+        tokenSessionId: z.ZodMiniNullable<z.ZodMiniString<string>>;
+        tokenCount: z.ZodMiniNumber<number>;
+        existingEntitiesPath: z.ZodMiniNullable<z.ZodMiniString<string>>;
+        /** Never 'running': the wizard starts its background cache check only once this has settled. */
+        existingEntitiesStatus: z.ZodMiniEnum<{
+            failed: "failed";
+            idle: "idle";
+            complete: "complete";
+        }>;
+        /** The only phases the scope gate can start from. */
+        compositionPhase: z.ZodMiniEnum<{
+            done: "done";
+            "cache-hit": "cache-hit";
+        }>;
+    }, z.core.$strip>>;
+    /**
+     * Present once the CLI has shown the scope gate, saved the decisions and generated the definitions; the wizard then
+     * starts at the review screen (or goes straight to pushing when nothing was accepted).
+     */
+    generation: z.ZodMiniOptional<z.ZodMiniDiscriminatedUnion<[z.ZodMiniObject<{
+        route: z.ZodMiniLiteral<"review">;
+        /** The session the generated definitions are in. The review screen opens it, and saving and pushing read it. */
+        sessionId: z.ZodMiniString<string>;
+        /** How many components the user accepted at the scope gate. */
+        acceptedCount: z.ZodMiniNumber<number>;
+        /** How many definitions were generated, which can differ from the accepted count. */
+        generatedCount: z.ZodMiniNumber<number>;
+        /**
+         * Whether token mapping was worth running (there were design props that are tokens, and tokens to map them from).
+         * The step count the wizard shows depends on it.
+         */
+        mapTokensEligible: z.ZodMiniBoolean<boolean>;
+    }, z.core.$strip>, z.ZodMiniObject<{
+        route: z.ZodMiniLiteral<"push">;
+        acceptedCount: z.ZodMiniLiteral<0>;
+    }, z.core.$strip>], "route">>;
+}, z.core.$strip>;
+export type ImportHandoff = z.infer<typeof ImportHandoffSchema>;
+export type ExtractionHandoff = NonNullable<ImportHandoff['extraction']>;
+export type GenerationHandoff = NonNullable<ImportHandoff['generation']>;
+export type ParsedHandoff = {
+    ok: true;
+    handoff: ImportHandoff;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function serializeHandoff(handoff: ImportHandoff): string;
+/** Reads the handoff from the variable's value. Never throws: a bad handoff comes back as an error to show. */
+export declare function parseHandoff(raw: string | undefined): ParsedHandoff;
+export {};

package/dist/src/handoff/index.js

@@ -0,0 +1,78 @@
+import * as z from 'zod/mini';
+// What the CLI's earlier import stages produced, as the later ones receive it: paths, ids and statuses only, no
+// credentials. The CLI now runs every stage in one process and passes this in memory; the environment variable name is
+// kept because the legacy `import` command, which is still shipped, reads the same document from it.
+//
+// When the legacy `import` command is removed, so is the environment variable.
+export const HANDOFF_ENV = 'EDS_IMPORT_HANDOFF';
+const NonEmpty = z.string().check(z.minLength(1));
+const TokensSchema = z.object({
+    /**
+     * What to do about an existing `tokens.json`.
+     * reuse: keep it. regenerate: build it again with the cache off. generate: nothing was asked, build it as usual.
+     */
+    strategy: z.enum(['reuse', 'regenerate', 'generate']),
+});
+const ExtractionSchema = z.object({
+    sessionId: NonEmpty,
+    outDir: NonEmpty,
+    tokensPath: z.string(),
+    tokenSessionId: z.nullable(z.string()),
+    tokenCount: z.number(),
+    existingEntitiesPath: z.nullable(z.string()),
+    /** Never 'running': the wizard starts its background cache check only once this has settled. */
+    existingEntitiesStatus: z.enum(['idle', 'complete', 'failed']),
+    /** The only phases the scope gate can start from. */
+    compositionPhase: z.enum(['done', 'cache-hit']),
+});
+const GenerationSchema = z.discriminatedUnion('route', [
+    /** At least one component was accepted: the definitions were generated and the wizard opens the review screen. */
+    z.object({
+        route: z.literal('review'),
+        /** The session the generated definitions are in. The review screen opens it, and saving and pushing read it. */
+        sessionId: NonEmpty,
+        /** How many components the user accepted at the scope gate. */
+        acceptedCount: z.number(),
+        /** How many definitions were generated, which can differ from the accepted count. */
+        generatedCount: z.number(),
+        /**
+         * Whether token mapping was worth running (there were design props that are tokens, and tokens to map them from).
+         * The step count the wizard shows depends on it.
+         */
+        mapTokensEligible: z.boolean(),
+    }),
+    /** Nothing was accepted: nothing is generated and the wizard goes straight to the push flow, as it always did. */
+    z.object({ route: z.literal('push'), acceptedCount: z.literal(0) }),
+]);
+const ImportHandoffSchema = z.object({
+    /** The user skipped the credentials screen, so nothing is fetched from or pushed to Contentful. */
+    credentialsSkipped: z.boolean(),
+    tokens: TokensSchema,
+    /** Present once the CLI has run the extraction stage; the wizard then starts at the scope gate. */
+    extraction: z.optional(ExtractionSchema),
+    /**
+     * Present once the CLI has shown the scope gate, saved the decisions and generated the definitions; the wizard then
+     * starts at the review screen (or goes straight to pushing when nothing was accepted).
+     */
+    generation: z.optional(GenerationSchema),
+});
+export function serializeHandoff(handoff) {
+    return JSON.stringify(handoff);
+}
+/** Reads the handoff from the variable's value. Never throws: a bad handoff comes back as an error to show. */
+export function parseHandoff(raw) {
+    if (!raw)
+        return { ok: false, error: `${HANDOFF_ENV} is not set. The import flow must be started by the CLI.` };
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, error: `${HANDOFF_ENV} is not valid JSON.` };
+    }
+    const result = z.safeParse(ImportHandoffSchema, json);
+    if (result.success)
+        return { ok: true, handoff: result.data };
+    const problems = result.error.issues.map((issue) => `${issue.path.join('.') || 'handoff'}: ${issue.message}`);
+    return { ok: false, error: `${HANDOFF_ENV} is invalid (${problems.join('; ')}).` };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-types",
-  "version": "2.38.0",
+  "version": "2.38.1-dev-build-6d903339.0",
   "license": "MIT",
   "type": "module",
   "module": "./dist/src/index.js",
@@ -16,6 +16,11 @@
       "types": "./dist/src/config/index.d.ts",
       "import": "./dist/src/config/index.js",
       "node": "./dist/src/config/index.js"
+    },
+    "./handoff": {
+      "types": "./dist/src/handoff/index.d.ts",
+      "import": "./dist/src/handoff/index.js",
+      "node": "./dist/src/handoff/index.js"
     }
   },
   "publishConfig": {