basecamp · jeremy · Jul 25, 2026 · chatgpt-codex-connector · Jul 25, 2026 · cubic-dev-ai
diff --git a/conformance/runner/typescript/live-dispatch.ts b/conformance/runner/typescript/live-dispatch.ts
@@ -81,6 +81,32 @@ export const LIVE_OPERATIONS: Record<string, DispatchSpec> = {
     },
   },
 
+  ListRecordings: {
+    fixtures: [],
+    call: async (ctx) => {
+      // Backs the type=Door external-links canary; validates the door shape
+      // (external url + service + description) against the Recording schema.
+      const result = await ctx.client.recordings.list("Door");
+      return { resolvedIds: {}, result };
+    },
+  },
+
+  GetProgressReport: {
+    fixtures: [],
+    call: async (ctx) => {
+      const result = await ctx.client.reports.progress();
+      return { resolvedIds: {}, result };
+    },
+  },
+
+  GetBubbleUps: {
+    fixtures: [],
+    call: async (ctx) => {
+      const result = await ctx.client.myNotifications.bubbleUps();
+      return { resolvedIds: {}, result };
+    },
+  },
+
   GetMyProfile: {
     fixtures: [],
     call: async (ctx) => {

diff --git a/conformance/tests/live-my-surface.json b/conformance/tests/live-my-surface.json
@@ -182,5 +182,19 @@
       { "type": "liveCallSucceeds" },
       { "type": "liveSchemaValidate" }
     ]
+  },
+  {
+    "mode": "live",
+    "name": "ListRecordings type=Door decodes the external-link (door) shape",
+    "description": "DECODING coverage for the absorbed external-links/doors list surface (spec/api-gaps/external-links-doors.md, bc3 #12375). Drives the type=Door recordings query and validates each recording against the Recording schema, including the door-specific url/service/description/position fields. Live-dormant: validates statically until credentials are provisioned. Create/image/composite remain residual gaps (see the entry).",
+    "operation": "ListRecordings",
+    "method": "GET",
+    "path": "/projects/recordings.json",
+    "queryParams": { "type": "Door" },
+    "tags": ["live", "read-only", "bc5-additive"],
+    "liveAssertions": [
+      { "type": "liveCallSucceeds" },
+      { "type": "liveSchemaValidate" }
+    ]
   }
 ]
diff --git a/go/pkg/basecamp/recordings.go b/go/pkg/basecamp/recordings.go
@@ -17,6 +17,7 @@ type RecordingType string
 const (
 	RecordingTypeComment        RecordingType = "Comment"
 	RecordingTypeDocument       RecordingType = "Document"
+	RecordingTypeDoor           RecordingType = "Door"
 	RecordingTypeKanbanCard     RecordingType = "Kanban::Card"
 	RecordingTypeKanbanStep     RecordingType = "Kanban::Step"
 	RecordingTypeMessage        RecordingType = "Message"
@@ -61,9 +62,28 @@ type Recording struct {
 	CommentsCount          int                   `json:"comments_count,omitempty"`
 	CommentsURL            string                `json:"comments_url,omitempty"`
 	SubscriptionURL        string                `json:"subscription_url,omitempty"`
-	Parent                 *Parent               `json:"parent,omitempty"`
-	Bucket                 *Bucket               `json:"bucket,omitempty"`
-	Creator                *Person               `json:"creator,omitempty"`
+	// Position, Description, and Service are door-specific (external-link)
+	// fields, populated only on Door recordings returned by the type=Door
+	// recordings query (the only endpoint that returns the full door shape).
+	// See spec/api-gaps/external-links-doors.md.
+	Position    int32        `json:"position,omitempty"`
+	Description string       `json:"description,omitempty"`
+	Service     *DoorService `json:"service,omitempty"`
+	Parent      *Parent      `json:"parent,omitempty"`
+	Bucket      *Bucket      `json:"bucket,omitempty"`
+	Creator     *Person      `json:"creator,omitempty"`
+}
+
+// DoorService describes the recognized external service backing an external
+// link (Door recording): its display name, a canonical example URL, a short
+// code (or "other" for a generic link), the URL patterns Basecamp recognizes,
+// and human supporting text.
+type DoorService struct {
+	Name           string   `json:"name,omitempty"`
+	ExampleURL     string   `json:"example_url,omitempty"`
+	Code           string   `json:"code,omitempty"`
+	ValidPatterns  []string `json:"valid_patterns,omitempty"`
+	SupportingText string   `json:"supporting_text,omitempty"`
 }
 
 // DefaultRecordingLimit is the default number of recordings to return when no limit is specified.
@@ -425,5 +445,19 @@ func recordingFromGenerated(gr generated.Recording) Recording {
 	r.ContentAttachments = richTextAttachmentsPtrFromGenerated(gr.ContentAttachments)
 	r.DescriptionAttachments = richTextAttachmentsPtrFromGenerated(gr.DescriptionAttachments)
 
+	// Door-specific fields (populated only for type=Door recordings).
+	r.Position = gr.Position
+	r.Description = gr.Description
+	if gr.Service.Name != "" || gr.Service.Code != "" || gr.Service.ExampleUrl != "" ||
+		gr.Service.SupportingText != "" || len(gr.Service.ValidPatterns) > 0 {
+		r.Service = &DoorService{
+			Name:           gr.Service.Name,
+			ExampleURL:     gr.Service.ExampleUrl,
+			Code:           gr.Service.Code,
+			ValidPatterns:  append([]string(nil), gr.Service.ValidPatterns...),
+			SupportingText: gr.Service.SupportingText,
+		}
+	}
+
 	return r
 }
diff --git a/go/pkg/basecamp/recordings_test.go b/go/pkg/basecamp/recordings_test.go
@@ -268,6 +268,7 @@ func TestRecordingType_Constants(t *testing.T) {
 	}{
 		{RecordingTypeComment, "Comment"},
 		{RecordingTypeDocument, "Document"},
+		{RecordingTypeDoor, "Door"},
 		{RecordingTypeKanbanCard, "Kanban::Card"},
 		{RecordingTypeKanbanStep, "Kanban::Step"},
 		{RecordingTypeMessage, "Message"},
@@ -286,6 +287,86 @@ func TestRecordingType_Constants(t *testing.T) {
 	}
 }
 
+// TestRecording_UnmarshalDoor verifies that a type=Door recording (external
+// link) decodes with the full door shape — the outside url, the service struct,
+// the description, and the position — through the shared Recording projection.
+func TestRecording_UnmarshalDoor(t *testing.T) {
+	data := `[
+		{
+			"id": 1069480290,
+			"status": "active",
+			"visible_to_clients": false,
+			"created_at": "2026-07-22T15:51:54.872Z",
+			"updated_at": "2026-07-22T15:51:54.886Z",
+			"title": "Design system",
+			"inherits_status": true,
+			"type": "Door",
+			"url": "https://www.figma.com/file/abc123/Design-system",
+			"app_url": "https://3.basecampapi.com/195539477/buckets/2085958504/dock/doors/1069480290",
+			"position": 8,
+			"bucket": {"id": 2085958504, "name": "The Leto Laptop", "type": "Project"},
+			"creator": {"id": 1049715913, "name": "Victor Cooper"},
+			"service": {
+				"name": "Figma",
+				"example_url": "https://www.figma.com/file/aGVsbG8gZmlnbWEgZmlsZQ",
+				"code": "figma",
+				"valid_patterns": ["(.*?\\.)?figma\\.com(\\/.*)?"],
+				"supporting_text": "a file or project on Figma"
+			},
+			"description": "<div>Shared Figma workspace</div>"
+		}
+	]`
+
+	var recordings []Recording
+	if err := json.Unmarshal([]byte(data), &recordings); err != nil {
+		t.Fatalf("failed to unmarshal door recording: %v", err)
+	}
+	if len(recordings) != 1 {
+		t.Fatalf("expected 1 recording, got %d", len(recordings))
+	}
+	d := recordings[0]
+	if d.Type != "Door" {
+		t.Errorf("expected type Door, got %q", d.Type)
+	}
+	if d.URL != "https://www.figma.com/file/abc123/Design-system" {
+		t.Errorf("expected external url, got %q", d.URL)
+	}
+	if d.Position != 8 {
+		t.Errorf("expected position 8, got %d", d.Position)
+	}
+	if d.Description != "<div>Shared Figma workspace</div>" {
+		t.Errorf("unexpected description: %q", d.Description)
+	}
+	if d.Service == nil {
+		t.Fatal("expected service struct to be non-nil for a Door")
+	}
+	if d.Service.Name != "Figma" || d.Service.Code != "figma" {
+		t.Errorf("unexpected service name/code: %q/%q", d.Service.Name, d.Service.Code)
+	}
+	if len(d.Service.ValidPatterns) != 1 || d.Service.ValidPatterns[0] == "" {
+		t.Errorf("expected 1 valid_pattern, got %v", d.Service.ValidPatterns)
+	}
+	if d.Service.SupportingText != "a file or project on Figma" {
+		t.Errorf("unexpected supporting_text: %q", d.Service.SupportingText)
+	}
+}
+
+// TestRecording_UnmarshalNonDoorOmitsDoorFields verifies a non-door recording
+// leaves the door-specific fields empty (they are optional).
+func TestRecording_UnmarshalNonDoorOmitsDoorFields(t *testing.T) {
+	data := `{"id": 1, "type": "Message", "title": "Hi", "url": "https://x/1.json"}`
+	var r Recording
+	if err := json.Unmarshal([]byte(data), &r); err != nil {
+		t.Fatalf("failed to unmarshal: %v", err)
+	}
+	if r.Service != nil {
+		t.Errorf("expected nil service for non-door, got %+v", r.Service)
+	}
+	if r.Description != "" || r.Position != 0 {
+		t.Errorf("expected empty door fields, got description=%q position=%d", r.Description, r.Position)
+	}
+}
+
 func TestRecordingsListOptions_BuildsQueryParams(t *testing.T) {
 	// This is a structural test to ensure the options fields exist
 	opts := RecordingsListOptions{

diff --git a/go/pkg/generated/client.gen.go b/go/pkg/generated/client.gen.go
diff --git a/kotlin/sdk/src/commonMain/kotlin/com/basecamp/sdk/generated/models/DoorService.kt b/kotlin/sdk/src/commonMain/kotlin/com/basecamp/sdk/generated/models/DoorService.kt
@@ -0,0 +1,20 @@
+package com.basecamp.sdk.generated.models
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonObject
+
+/**
+ * DoorService entity from the Basecamp API.
+ *
+ * @generated from OpenAPI spec — do not edit directly
+ */
+@Serializable
+data class DoorService(
+    val name: String? = null,
+    @SerialName("example_url") val exampleUrl: String? = null,
+    val code: String? = null,
+    @SerialName("valid_patterns") val validPatterns: List<String> = emptyList(),
+    @SerialName("supporting_text") val supportingText: String? = null
+)
diff --git a/kotlin/sdk/src/commonMain/kotlin/com/basecamp/sdk/generated/models/Recording.kt b/kotlin/sdk/src/commonMain/kotlin/com/basecamp/sdk/generated/models/Recording.kt
@@ -31,5 +31,8 @@ data class Recording(
     @SerialName("description_attachments") val descriptionAttachments: List<RichTextAttachment>? = null,
     @SerialName("comments_count") val commentsCount: Int = 0,
     @SerialName("comments_url") val commentsUrl: String? = null,
-    @SerialName("subscription_url") val subscriptionUrl: String? = null
+    @SerialName("subscription_url") val subscriptionUrl: String? = null,
+    val position: Int = 0,
+    val description: String? = null,
+    val service: DoorService? = null
 )
diff --git a/kotlin/sdk/src/commonMain/kotlin/com/basecamp/sdk/generated/services/recordings.kt b/kotlin/sdk/src/commonMain/kotlin/com/basecamp/sdk/generated/services/recordings.kt
@@ -14,7 +14,7 @@ class RecordingsService(client: AccountClient) : BaseService(client) {
 
     /**
      * List recordings of a given type across projects
-     * @param type Comment|Document|Kanban::Card|Kanban::Step|Message|Question::Answer|Schedule::Entry|Todo|Todolist|Upload|Vault
+     * @param type Comment|Document|Door|Kanban::Card|Kanban::Step|Message|Question::Answer|Schedule::Entry|Todo|Todolist|Upload|Vault
      * @param options Optional query parameters and pagination control
      */
     suspend fun list(type: String, options: ListRecordingsOptions? = null): ListResult<Recording> {

diff --git a/openapi.json b/openapi.json
@@ -10253,10 +10253,10 @@
           {
             "name": "type",
             "in": "query",
-            "description": "Comment|Document|Kanban::Card|Kanban::Step|Message|Question::Answer|Schedule::Entry|Todo|Todolist|Upload|Vault",
+            "description": "Comment|Document|Door|Kanban::Card|Kanban::Step|Message|Question::Answer|Schedule::Entry|Todo|Todolist|Upload|Vault",
             "schema": {
               "type": "string",
-              "description": "Comment|Document|Kanban::Card|Kanban::Step|Message|Question::Answer|Schedule::Entry|Todo|Todolist|Upload|Vault"
+              "description": "Comment|Document|Door|Kanban::Card|Kanban::Step|Message|Question::Answer|Schedule::Entry|Todo|Todolist|Upload|Vault"
             },
             "required": true,
             "examples": {
@@ -23844,6 +23844,30 @@
           "visible_to_clients"
         ]
       },
+      "DoorService": {
+        "type": "object",
+        "description": "Metadata describing the recognized external service backing an external link\n(`Door` recording): its display name, a canonical example URL, a short code,\nthe URL patterns Basecamp recognizes for it, and human supporting text. `code`\nis `other` for a generic link.",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "example_url": {
+            "type": "string"
+          },
+          "code": {
+            "type": "string"
+          },
+          "valid_patterns": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "supporting_text": {
+            "type": "string"
+          }
+        }
+      },
       "EnableCardColumnOnHoldResponseContent": {
         "$ref": "#/components/schemas/CardColumn"
       },
@@ -26591,7 +26615,8 @@
             "type": "string"
           },
           "url": {
-            "type": "string"
+            "type": "string",
+            "description": "API URL of the recording. Exception: in the `type=Door` (external-link)\nprojection, `url` is the door's **external destination address** (e.g. the\nFigma/Dropbox URL) and `app_url` is the Basecamp redirector — see the\ndoor-specific `service`/`description` fields below."
           },
           "app_url": {
             "type": "string"
@@ -26626,6 +26651,18 @@
           "subscription_url": {
             "type": "string"
           },
+          "position": {
+            "type": "integer",
+            "description": "Ordinal position within the project's External links section. Present on\n`Door` (external-link) recordings.",
+            "format": "int32"
+          },
+          "description": {
+            "type": "string",
+            "description": "Rich-text (HTML) description shown beneath an external link. Present only\non `Door` recordings returned by the `type=Door` recordings query (the only\nendpoint that returns the full door shape). The external destination\naddress is `url` (not this field); `app_url` is the Basecamp redirector.\nSee `spec/api-gaps/external-links-doors.md`."
+          },
+          "service": {
+            "$ref": "#/components/schemas/DoorService"
+          },
           "parent": {
             "$ref": "#/components/schemas/RecordingParent"
           },