[pull] main from fern-api:main

docs-yml.schema.json

@@ -198,6 +198,19 @@
         }
       ]
     },
+    "translations": {
+      "oneOf": [
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/docs.TranslationConfig"
+          }
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
     "ai-chat": {
       "oneOf": [
         {
@@ -4265,6 +4278,28 @@
         "tr"
       ]
     },
+    "docs.TranslationConfig": {
+      "type": "object",
+      "properties": {
+        "lang": {
+          "$ref": "#/definitions/docs.Language"
+        },
+        "default": {
+          "oneOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "lang"
+      ],
+      "additionalProperties": false
+    },
     "docs.AIChatModel": {
       "type": "string",
       "enum": [

fern/apis/docs-yml/definition/docs.yml

@@ -42,6 +42,13 @@ types:
       - sv
       - tr
 
+  TranslationConfig:
+    properties:
+      lang: Language
+      default:
+        type: optional<boolean>
+        docs: Whether this language is the default. At most one entry should be marked as default.
+
   AnalyticsConfig:
     properties:
       segment: optional<SegmentConfig>
@@ -273,6 +280,22 @@ types:
 
       languages: optional<list<Language>>
 
+      translations:
+        type: optional<list<TranslationConfig>>
+        docs: |
+          Configuration for multi-language documentation. Each entry defines a locale
+          that the documentation supports. Use the `translations/` directory alongside
+          `docs.yml` to provide per-language content.
+
+          Example:
+          ```yaml
+          translations:
+            - lang: en
+              default: true
+            - lang: ja
+            - lang: fr
+          ```
+
       # Deprecated
       "ai-chat": optional<AIChatConfig>
 

generators/go-v2/base/package.json

@@ -43,7 +43,7 @@
     "@fern-api/go-ast": "workspace:*",
     "@fern-api/logging-execa": "workspace:*",
     "@fern-fern/generator-exec-sdk": "catalog:",
-    "@fern-fern/ir-sdk": "66.0.0",
+    "@fern-fern/ir-sdk": "66.3.0",
     "@types/node": "catalog:",
     "dedent": "catalog:",
     "typescript": "catalog:",

generators/go-v2/model/package.json

@@ -45,7 +45,7 @@
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/go-ast": "workspace:*",
     "@fern-api/go-base": "workspace:*",
-    "@fern-fern/ir-sdk": "66.0.0",
+    "@fern-fern/ir-sdk": "66.3.0",
     "@types/node": "catalog:",
     "typescript": "catalog:",
     "vitest": "catalog:"

generators/go-v2/sdk/package.json

@@ -42,6 +42,7 @@
     "@fern-api/base-generator": "workspace:*",
     "@fern-api/configs": "workspace:*",
     "@fern-api/core-utils": "workspace:*",
+    "@fern-api/dynamic-ir-sdk": "66.1.0",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/go-ast": "workspace:*",
     "@fern-api/go-base": "workspace:*",
@@ -50,11 +51,10 @@
     "@fern-api/mock-utils": "workspace:*",
     "@fern-fern/generator-cli-sdk": "^0.1.5",
     "@fern-fern/generator-exec-sdk": "catalog:",
-    "@fern-fern/ir-sdk": "66.0.0",
+    "@fern-fern/ir-sdk": "66.3.0",
     "@types/node": "catalog:",
     "dedent": "catalog:",
     "typescript": "catalog:",
-    "vitest": "catalog:",
-    "@fern-api/dynamic-ir-sdk": "66.1.0"
+    "vitest": "catalog:"
   }
 }

generators/go-v2/sdk/src/readme/ReadmeSnippetBuilder.ts

@@ -179,7 +179,7 @@ export class ReadmeSnippetBuilder extends AbstractReadmeSnippetBuilder {
         return this.writeCode(dedent`
             // Specify default options applied on every request.
             ${ReadmeSnippetBuilder.CLIENT_VARIABLE_NAME} := ${this.rootPackageClientName}.NewClient(
-                option.WithToken("<YOUR_API_KEY>"),
+                option.WithToken("${this.getTokenPlaceholder()}"),
                 option.WithHTTPClient(
                     &http.Client{
                         Timeout: 5 * time.Second,
@@ -190,7 +190,7 @@ export class ReadmeSnippetBuilder extends AbstractReadmeSnippetBuilder {
             // Specify options for an individual request.
             response, err := ${this.getMethodCall(endpoint)}(
                 ...,
-                option.WithToken("<YOUR_API_KEY>"),
+                option.WithToken("${this.getTokenPlaceholder()}"),
             )
         `);
     }
@@ -303,6 +303,28 @@ export class ReadmeSnippetBuilder extends AbstractReadmeSnippetBuilder {
         `);
     }
 
+    private getTokenPlaceholder({ defaultValue = "<YOUR_API_KEY>" }: { defaultValue?: string } = {}): string {
+        if (this.context.ir.auth != null) {
+            for (const scheme of this.context.ir.auth.schemes) {
+                if (scheme.type === "bearer" && scheme.tokenPlaceholder != null) {
+                    return scheme.tokenPlaceholder;
+                }
+                if (scheme.type === "header" && scheme.headerPlaceholder != null) {
+                    return scheme.headerPlaceholder;
+                }
+            }
+        }
+        return defaultValue;
+    }
+
+    private getOAuthClientIdPlaceholder(): string {
+        return "<YOUR_CLIENT_ID>";
+    }
+
+    private getOAuthClientSecretPlaceholder(): string {
+        return "<YOUR_CLIENT_SECRET>";
+    }
+
     private hasOAuthScheme(): boolean {
         if (this.context.ir.auth == null) {
             return false;
@@ -315,14 +337,14 @@ export class ReadmeSnippetBuilder extends AbstractReadmeSnippetBuilder {
             // Option 1: Use client credentials (SDK will handle token fetching and refresh)
             ${ReadmeSnippetBuilder.CLIENT_VARIABLE_NAME} := ${this.rootPackageClientName}.NewClient(
                 option.WithClientCredentials(
-                    "<YOUR_CLIENT_ID>",
-                    "<YOUR_CLIENT_SECRET>",
+                    "${this.getOAuthClientIdPlaceholder()}",
+                    "${this.getOAuthClientSecretPlaceholder()}",
                 ),
             )
 
             // Option 2: Use a pre-fetched token directly
             ${ReadmeSnippetBuilder.CLIENT_VARIABLE_NAME} := ${this.rootPackageClientName}.NewClient(
-                option.WithToken("<YOUR_ACCESS_TOKEN>"),
+                option.WithToken("${this.getTokenPlaceholder({ defaultValue: "<YOUR_ACCESS_TOKEN>" })}"),
             )
         `);
     }

generators/go-v2/sdk/src/wire-tests/WireTestSetupGenerator.ts

@@ -26,7 +26,9 @@ export class WireTestSetupGenerator {
     }
 
     public static getWiremockConfigContent(ir: FernIr.IntermediateRepresentation) {
-        return new WireMock().convertToWireMock(ir);
+        // ir-sdk versions may differ between go-sdk (66.3.0) and mock-utils (66.0.0);
+        // 66.3.0 is a strict superset (adds optional fields only), so this is safe.
+        return new WireMock().convertToWireMock(ir as Parameters<WireMock["convertToWireMock"]>[0]);
     }
 
     private generateWireMockConfigFile(): void {

generators/go/sdk/changes/1.38.0/feat-auth-placeholder-snippets.yml

@@ -0,0 +1,4 @@
+- summary: |
+    Use auth scheme placeholder values in README snippets when configured via
+    `placeholder` field on auth schemes.
+  type: feat

generators/go/sdk/versions.yml

@@ -1,4 +1,12 @@
 # yaml-language-server: $schema=../../../fern-versions-yml.schema.json
+- version: 1.38.0
+  changelogEntry:
+    - summary: |
+        Use auth scheme placeholder values in README snippets when configured via
+        `placeholder` field on auth schemes.
+      type: feat
+  createdAt: "2026-04-27"
+  irVersion: 66
 - version: 1.37.0
   changelogEntry:
     - summary: |

generators/java/generator-utils/src/main/java/com/fern/java/generators/UndiscriminatedUnionGenerator.java

@@ -29,6 +29,8 @@
 import com.fern.ir.model.types.ContainerType;
 import com.fern.ir.model.types.DeclaredTypeName;
 import com.fern.ir.model.types.Literal;
+import com.fern.ir.model.types.ObjectProperty;
+import com.fern.ir.model.types.ObjectTypeDeclaration;
 import com.fern.ir.model.types.PrimitiveType;
 import com.fern.ir.model.types.PrimitiveTypeV1;
 import com.fern.ir.model.types.TypeDeclaration;
@@ -54,6 +56,7 @@
 import com.squareup.javapoet.TypeName;
 import com.squareup.javapoet.TypeSpec;
 import com.squareup.javapoet.TypeVariableName;
+import com.squareup.javapoet.WildcardTypeName;
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.Collections;
@@ -604,6 +607,28 @@ private TypeSpec getDeserializer() {
             if (typeName.isPrimitive() || typeName.isBoxedPrimitive()) {
                 continue;
             }
+            List<String> requiredKeys = getRequiredWireKeys(member);
+            boolean hasRequiredKeyGuard = !requiredKeys.isEmpty();
+            if (hasRequiredKeyGuard) {
+                ParameterizedTypeName mapWildcard = ParameterizedTypeName.get(
+                        ClassName.get(Map.class),
+                        WildcardTypeName.subtypeOf(Object.class),
+                        WildcardTypeName.subtypeOf(Object.class));
+                StringBuilder guard = new StringBuilder();
+                guard.append("$L instanceof $T");
+                for (String key : requiredKeys) {
+                    guard.append(" && (($T) $L).containsKey($S)");
+                }
+                List<Object> guardArgs = new ArrayList<>();
+                guardArgs.add(VALUE_FIELD_SPEC.name);
+                guardArgs.add(mapWildcard);
+                for (String key : requiredKeys) {
+                    guardArgs.add(mapWildcard);
+                    guardArgs.add(VALUE_FIELD_SPEC.name);
+                    guardArgs.add(key);
+                }
+                deserializeMethod.beginControlFlow("if (" + guard.toString() + ")", guardArgs.toArray());
+            }
             if (shouldDeserializeWithTypeReference(member)) {
                 deserializeMethod
                         .beginControlFlow("try")
@@ -629,6 +654,9 @@ private TypeSpec getDeserializer() {
                         .nextControlFlow("catch($T e)", RuntimeException.class)
                         .endControlFlow();
             }
+            if (hasRequiredKeyGuard) {
+                deserializeMethod.endControlFlow();
+            }
         }
         deserializeMethod.addStatement("throw new $T(p, $S)", JsonParseException.class, "Failed to deserialize");
         return deserializerBuilder.addMethod(deserializeMethod.build()).build();
@@ -659,6 +687,76 @@ private boolean shouldDeserializeWithTypeReference(UndiscriminatedUnionMember me
         return false;
     }
 
+    /**
+     * Returns the wire keys of all required (non-optional, non-nullable, non-literal) properties for an object-typed
+     * union member. Returns an empty list for non-object members. This is used to emit key-presence guards in the
+     * deserializer so that trial-order deserialization doesn't misclassify payloads when the Jackson builder silently
+     * accepts missing fields.
+     */
+    private List<String> getRequiredWireKeys(UndiscriminatedUnionMember member) {
+        if (!member.getType().isNamed()) {
+            return Collections.emptyList();
+        }
+        TypeId typeId = member.getType().getNamed().get().getTypeId();
+        // Walk alias chains until we hit a non-alias type declaration. Guards against alias cycles
+        // with a visited-set keyed by TypeId.
+        Set<TypeId> visited = new HashSet<>();
+        while (typeId != null && visited.add(typeId)) {
+            TypeDeclaration typeDeclaration =
+                    generatorContext.getTypeDeclarations().get(typeId);
+            if (typeDeclaration == null) {
+                return Collections.emptyList();
+            }
+            if (typeDeclaration.getShape().isObject()) {
+                ObjectTypeDeclaration objectType =
+                        typeDeclaration.getShape().getObject().get();
+                List<String> requiredKeys = new ArrayList<>();
+                collectRequiredWireKeys(objectType, requiredKeys);
+                return requiredKeys;
+            }
+            if (!typeDeclaration.getShape().isAlias()) {
+                // Enum / union / undiscriminated union / etc. — convertValue will reject a JSON
+                // object naturally for these, so no presence guard is needed.
+                return Collections.emptyList();
+            }
+            com.fern.ir.model.types.ResolvedTypeReference resolved =
+                    typeDeclaration.getShape().getAlias().get().getResolvedType();
+            if (!resolved.isNamed()) {
+                // Resolved to primitive / container / unknown — not an object shape.
+                return Collections.emptyList();
+            }
+            typeId = resolved.getNamed().get().getName().getTypeId();
+        }
+        return Collections.emptyList();
+    }
+
+    private void collectRequiredWireKeys(ObjectTypeDeclaration objectType, List<String> requiredKeys) {
+        for (ObjectProperty property : objectType.getProperties()) {
+            if (isRequiredProperty(property)) {
+                requiredKeys.add(NameUtils.getWireValue(property.getName()));
+            }
+        }
+        // Include required properties from extended types
+        for (DeclaredTypeName extendedType : objectType.getExtends()) {
+            TypeDeclaration extDeclaration =
+                    generatorContext.getTypeDeclarations().get(extendedType.getTypeId());
+            if (extDeclaration != null && extDeclaration.getShape().isObject()) {
+                collectRequiredWireKeys(extDeclaration.getShape().getObject().get(), requiredKeys);
+            }
+        }
+    }
+
+    private static boolean isRequiredProperty(ObjectProperty property) {
+        com.fern.ir.model.types.TypeReference valueType = property.getValueType();
+        if (valueType.isContainer()) {
+            ContainerType container = valueType.getContainer().get();
+            if (container.isOptional() || container.isNullable() || container.isLiteral()) {
+                return false;
+            }
+        }
+        return true;
+    }
+
     private static String visitorName(Set<String> reservedTypeNames) {
         return reservedTypeNames.contains(VISITOR_CLASS_NAME) ? VISITOR_CLASS_NAME_UNDERSCORE : VISITOR_CLASS_NAME;
     }