Absorb everything-aggregates flat family (bc3 #11627, PR-5 of 2)

[jeremy]

Closes #434 (partially — flat family only). Part of the post-#401 BC3 follow-up absorption program (PR-5, the LARGE one, two-phase).

Stacked on #431 (PR-4) → #426 → #424 → #419 → #416. Base is doors-external-links; review the PR-5 commit only. Will retarget to main as the stack merges.

Summary

BC5's account-wide recording listings (documented by bc3 #11627) had no SDK surface. This adds a new EverythingService with the flat family (8 ops), mirroring the flat-aggregate pattern of GetMyAssignments. The bucket-grouped family (9 sub-routes) lands in PR-5b; the registry entry stays partial-coverage until then.

Absorbed

• 6 Link-paginated roots — GetEverythingMessages/Comments/Checkins/Forwards (element = the generic Recording projection the wire returns, embedding bucket), GetEverythingBoosts (Boost), GetEverythingFiles.
• 2 unpaginated oldest-first arrays — GetEverythingOverdueTodos (Todo), GetEverythingOverdueCards (Card) — bare arrays via smithy-bare-arrays, tested with no Link-following.
• /files.json heterogeneous (Upload + Document + attachment-envelope) → optional-field superset EverythingFile with kind + repeatable people_ids[] filters.

Runtime decode proof (all six SDKs)

A non-empty test decoding all three file variants in one array — Go, TS, Ruby, Python, Kotlin, Swift. Kotlin needed EverythingFile added to the generator TYPE_ALIASES (else it fell back to ListResult<JsonElement>); it now returns ListResult<EverythingFile>. Go tests also cover multi-page Link-following, unpaginated-with-Link-header-ignored, and the kind/people_ids[] filters.

Wiring

Service auto-derives from the Everything tag; client wiring added where hand-written (Go accessor, TS defineService, Ruby method, Python sync+async properties; Kotlin/Swift auto-wired).

Verification

make generate && make check — clean (all six SDK suites, conformance, wrapper/Kotlin drift, 24 api-gap entries). everything-aggregates.md → partial-coverage. Conformance paths.json/dispatch + per-group canary entries tracked as follow-ups landing with PR-5b.

---

Summary by cubic

Adds a new EverythingService that exposes account‑wide “everything” listings (flat family, 8 ops) across all SDKs. Partially addresses #434 and aligns with bc3 #11627; bucket‑grouped routes will ship in PR‑5b.

• New Features

  • New EverythingService with 8 ops: GetEverythingMessages, GetEverythingComments, GetEverythingCheckins, GetEverythingForwards, GetEverythingBoosts, GetEverythingFiles, GetEverythingOverdueTodos, GetEverythingOverdueCards.
  • Pagination: Link-following for the six recency-ordered roots; overdue todos/cards return full arrays.
  • /files.json heterogeneous feed modeled as EverythingFile with kind and repeatable people_ids[] filters; Go uses nullable FlexInt for width/height.
  • Wired across Go/TypeScript/Ruby/Python/Kotlin/Swift; OpenAPI/smithy/metadata updated; tests prove decode and pagination.

• Migration

  • No breaking changes. New accessors: Go accountClient.Everything(), TypeScript client.everything, Python client.everything, Ruby client.everything, Kotlin accountClient.everything, Swift accountClient.everything.

^{Written for commit 62dad6f. Summary will update on new commits.}

[github-actions]

Spec Change Impact

• Modifications:

  • Operations/types/resources have been modified (details not provided in the diff snippet).

• Additions: No new operations/types/resources were explicitly mentioned.

• Removals: No removed operations/types/resources were explicitly mentioned, but if any exist, this is a breaking API change.

• SDK Regeneration: Required for all SDKs due to spec changes, even for non-breaking changes.

• Breaking Change: Unable to confirm without more details. If operations or fields were removed, this is a breaking change.

Checklist of SDKs Needing Updates:

• Go
• TypeScript
• Ruby
• Kotlin
• Swift

[Copilot]

⚠️ Not ready to approve

The Go wrapper’s page parameter is currently not applied to requests (so page>1 can’t work as documented), and the TS/Python client typings have a few inconsistencies that should be corrected before merging.

Pull request overview

Adds first-phase SDK surface for BC5 “everything” account-wide aggregates (flat family, 8 ops) by introducing a new EverythingService across all six SDKs, backed by Smithy/OpenAPI updates, runtime decode fixtures for the heterogeneous /files.json feed, and updated api-gaps registry status.

[!TIP]
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Changes:

• Model and generate the flat “everything” aggregate routes (messages/comments/checkins/forwards/boosts/files + overdue todos/cards) and tag them into a new Everything service group.
• Add per-SDK wiring so client.everything / account.everything is available, plus metadata/path mapping updates.
• Add runtime decode tests proving /files.json heterogeneous variants (Upload/Document/Attachment) decode correctly across SDKs.

File summaries

File	Description
typescript/tests/services/everything.test.ts	Adds TS decode test for heterogeneous /files.json results.
typescript/src/generated/services/index.ts	Exports generated EverythingService.
typescript/src/generated/services/everything.ts	Implements generated TS EverythingService methods for the flat family.
typescript/src/generated/schema.d.ts	Adds new operations/paths and EverythingFile schema typing.
typescript/src/generated/path-mapping.ts	Maps Everything endpoints to operation IDs for routing/metadata.
typescript/src/generated/openapi-stripped.json	Updates stripped OpenAPI with Everything routes/schemas used by TS generator.
typescript/src/generated/metadata.ts	Adds retry/pagination metadata entries for Everything operations.
typescript/src/client.ts	Wires client.everything service accessor.
swift/Tests/BasecampTests/GeneratedServiceTests.swift	Adds Swift runtime decode test for heterogeneous /files.json.
swift/Sources/Basecamp/Generated/Services/EverythingService.swift	Adds generated Swift EverythingService.
swift/Sources/Basecamp/Generated/Models/EverythingFile.swift	Adds generated Swift EverythingFile model.
swift/Sources/Basecamp/Generated/Metadata.swift	Registers retry metadata for Everything operations.
swift/Sources/Basecamp/Generated/AccountClient+Services.swift	Wires Swift account.everything accessor.
spec/overlays/tags.smithy	Tags the 8 flat-family operations into the Everything service group.
spec/basecamp.smithy	Adds Smithy operations + EverythingFile superset shape.
spec/api-gaps/README.md	Marks everything-aggregates as partial-coverage pending PR-5b.
spec/api-gaps/everything-aggregates.md	Updates registry entry with phased plan/status + smithy refs.
scripts/enhance-openapi-go-types.sh	Enhances EverythingFile width/height to nullable FlexInt in Go OpenAPI post-pass.
ruby/test/basecamp/services/everything_service_test.rb	Adds Ruby decode test for heterogeneous /files.json.
ruby/lib/basecamp/generated/types.rb	Adds generated Ruby EverythingFile type class.
ruby/lib/basecamp/generated/services/everything_service.rb	Adds generated Ruby EverythingService.
ruby/lib/basecamp/generated/metadata.json	Registers Ruby operation metadata for Everything operations.
ruby/lib/basecamp/client.rb	Wires Ruby client.everything accessor.
python/tests/services/test_everything.py	Adds Python decode test for heterogeneous /files.json.
python/src/basecamp/generated/types.py	Adds EverythingFile TypedDict.
python/src/basecamp/generated/services/everything.py	Adds generated Python sync/async EverythingService.
python/src/basecamp/generated/services/init.py	Exposes Everything services via package exports.
python/src/basecamp/generated/metadata.json	Registers retry metadata for Everything operations.
python/src/basecamp/client.py	Wires Python sync client.everything property.
python/src/basecamp/async_client.py	Wires Python async client.everything property.
openapi.json	Adds Everything paths/operations/schemas to the canonical OpenAPI output.
kotlin/sdk/src/commonTest/kotlin/com/basecamp/sdk/EverythingFilesDecodeTest.kt	Adds Kotlin decode test for heterogeneous /files.json.
kotlin/sdk/src/commonMain/kotlin/com/basecamp/sdk/generated/services/Types.kt	Adds options type for Everything files filters/pagination.
kotlin/sdk/src/commonMain/kotlin/com/basecamp/sdk/generated/services/everything.kt	Adds generated Kotlin EverythingService.
kotlin/sdk/src/commonMain/kotlin/com/basecamp/sdk/generated/ServiceAccessors.kt	Wires Kotlin accountClient.everything accessor.
kotlin/sdk/src/commonMain/kotlin/com/basecamp/sdk/generated/models/EverythingFile.kt	Adds generated Kotlin EverythingFile model.
kotlin/sdk/src/commonMain/kotlin/com/basecamp/sdk/generated/Metadata.kt	Registers retry config entries for Everything operations.
kotlin/generator/src/main/kotlin/com/basecamp/sdk/generator/Config.kt	Adds EverythingFile to Kotlin generator TYPE_ALIASES.
go/pkg/basecamp/url-routes.json	Registers Everything routes in Go URL routing table.
go/pkg/basecamp/everything.go	Adds Go EverythingService wrapper + EverythingFile public model conversion.
go/pkg/basecamp/everything_test.go	Adds Go tests for Link-following, filters, and heterogeneous decode.
go/pkg/basecamp/client.go	Wires Go AccountClient.Everything() accessor.
behavior-model.json	Adds behavior-model entries for Everything operations (retry/pagination/readonly).

Review details

• Files reviewed: 21/44 changed files
• Comments generated: 1
• Review effort level: Low

Note

Your feedback helps us improve the quality of this feature.
Please use 👍 or 👎 to tell us whether this assessment is correct.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 62dad6fa41

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Add contract tests for all eight operations

The new TypeScript suite exercises only the happy path for everythingFiles, and the Ruby and Python suites have the same limitation; the other seven operations have neither happy-path nor error tests, while everythingFiles has no error test. Consequently, incorrect routes, response shapes, and error propagation for most of this service can ship undetected. The repository's completeness bar explicitly requires happy-path and error coverage in all three SDKs for every new operation.

AGENTS.md reference: AGENTS.md:L305-L307

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Export EverythingService from the package root

Although this adds EverythingService to the generated services barrel, the package entry point typescript/src/index.ts explicitly enumerates public service exports and is not updated here. Consumers therefore cannot import EverythingService or its option types from @37signals/basecamp, unlike the other public services; add the corresponding root export.

AGENTS.md reference: AGENTS.md:L304-L304

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Refresh provenance for this upstream absorption

This Smithy addition explicitly absorbs the BC3 #11627 contract, but the commit does not update spec/api-provenance.json. That leaves no recorded upstream HEAD/date for the sync and prevents the provenance pin from demonstrating which BC3 state was verified; refresh the pin and run make provenance-sync.

AGENTS.md reference: AGENTS.md:L265-L270

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Forward the requested page in Go

When a caller passes page > 1, this request still invokes the generated operation without a page parameter, so it always fetches the API's default first page and merely disables Link following afterward. The same omission affects Comments, Checkins, Forwards, Boosts, and Files. Add the page query parameter to the six Smithy inputs, regenerate, and pass it through so requesting page 2 does not silently return page 1.

AGENTS.md reference: AGENTS.md:L76-L76

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Preserve ListResult in the TypeScript return types

For everythingBoosts, the declared response alias resolves to Boost[], even though requestPaginated returns ListResult<Boost> and the method documentation promises .meta.totalCount. TypeScript consumers therefore get a compile-time error when accessing the advertised metadata; everythingFiles has the same issue. Update the generator's entity mapping so these signatures are ListResult<Boost> and ListResult<EverythingFile>.

Useful? React with 👍 / 👎.

[cubic-dev-ai]

6 issues found across 44 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="go/pkg/basecamp/everything.go">

<violation number="1" location="go/pkg/basecamp/everything.go:62">
P3: False API values are lost when callers marshal `EverythingFile`. Keep JSON tags on these response booleans without `omitempty` so `false` is represented.</violation>

<violation number="2" location="go/pkg/basecamp/everything.go:63">
P3: Attachment variants with no timestamps serialize zero-time sentinels instead of preserving field absence. Use `*time.Time` for optional timestamps and populate them only when the generated value is present/non-zero.</violation>

<violation number="3" location="go/pkg/basecamp/everything.go:169">
P2: Passing a positive page returns the server's first page, not the requested page, across every paginated Everything method. Add `page` to the initial request query (for example via a request editor) or document/remove this parameter rather than promising a page-specific result.</violation>
</file>

<file name="typescript/src/client.ts">

<violation number="1" location="typescript/src/client.ts:411">
P2: EverythingService is wired into the client (import, type declaration, `defineService`) but not re-exported from `index.ts`, so it is missing from the package's public API surface. All other services in the codebase are re-exported — please add a re-export block for `EverythingService` (and any newly exported types like `EverythingFile`) to `index.ts` following the same pattern.</violation>
</file>

<file name="python/src/basecamp/client.py">

<violation number="1" location="python/src/basecamp/client.py:351">
P1: The new `account.everything` accessor exposes overdue methods with the wrong response contract: `get_everything_overdue_cards` and `get_everything_overdue_todos` call `_request` and are typed as `dict[str, Any]`, but these routes return bare arrays. A valid overdue response therefore violates the SDK method contract and can break callers expecting the documented list result; the generated service should use the bare-array response handling and list return type for both sync and async methods.</violation>
</file>

<file name="typescript/src/generated/services/everything.ts">

<violation number="1" location="typescript/src/generated/services/everything.ts:182">
P2: `everythingFiles` is paginated at runtime, but the declared return type is a plain array response alias. Using `ListResult<...>` in the signature preserves typed access to pagination metadata and matches the method’s actual return contract.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: The new account.everything accessor exposes overdue methods with the wrong response contract: get_everything_overdue_cards and get_everything_overdue_todos call _request and are typed as dict[str, Any], but these routes return bare arrays. A valid overdue response therefore violates the SDK method contract and can break callers expecting the documented list result; the generated service should use the bare-array response handling and list return type for both sync and async methods.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At python/src/basecamp/client.py, line 351:

<comment>The new `account.everything` accessor exposes overdue methods with the wrong response contract: `get_everything_overdue_cards` and `get_everything_overdue_todos` call `_request` and are typed as `dict[str, Any]`, but these routes return bare arrays. A valid overdue response therefore violates the SDK method contract and can break callers expecting the documented list result; the generated service should use the bare-array response handling and list return type for both sync and async methods.</comment>

<file context>
@@ -344,6 +344,12 @@ def timeline(self):
+    def everything(self):
+        from basecamp.generated.services.everything import EverythingService
+
+        return self._service("everything", lambda: EverythingService(self))
+
     @property
</file context>

[cubic-dev-ai]

P2: Passing a positive page returns the server's first page, not the requested page, across every paginated Everything method. Add page to the initial request query (for example via a request editor) or document/remove this parameter rather than promising a page-specific result.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At go/pkg/basecamp/everything.go, line 169:

<comment>Passing a positive page returns the server's first page, not the requested page, across every paginated Everything method. Add `page` to the initial request query (for example via a request editor) or document/remove this parameter rather than promising a page-specific result.</comment>

<file context>
@@ -0,0 +1,437 @@
+// Messages returns every message across all accessible projects, newest-first.
+// Pass a positive page to return only that page; page 0 follows the Link header
+// across all pages.
+func (s *EverythingService) Messages(ctx context.Context, page int32) (result *RecordingsPage, err error) {
+	op := OperationInfo{Service: "Everything", Operation: "Messages", ResourceType: "recording", IsMutation: false}
+	ctx, done, err := s.begin(ctx, op)
</file context>

[cubic-dev-ai]

P2: EverythingService is wired into the client (import, type declaration, defineService) but not re-exported from index.ts, so it is missing from the package's public API surface. All other services in the codebase are re-exported — please add a re-export block for EverythingService (and any newly exported types like EverythingFile) to index.ts following the same pattern.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At typescript/src/client.ts, line 411:

<comment>EverythingService is wired into the client (import, type declaration, `defineService`) but not re-exported from `index.ts`, so it is missing from the package's public API surface. All other services in the codebase are re-exported — please add a re-export block for `EverythingService` (and any newly exported types like `EverythingFile`) to `index.ts` following the same pattern.</comment>

<file context>
@@ -405,6 +408,7 @@ export function createBasecampClient(options: BasecampClientOptions): BasecampCl
   defineService("tools", () => new ToolsService(client, hooks, fetchPage, maxPages));
   defineService("timesheets", () => new TimesheetsService(client, hooks, fetchPage, maxPages));
   defineService("timeline", () => new TimelineService(client, hooks, fetchPage, maxPages));
+  defineService("everything", () => new EverythingService(client, hooks, fetchPage, maxPages));
   defineService("clientVisibility", () => new ClientVisibilityService(client, hooks, fetchPage, maxPages));
   defineService("boosts", () => new BoostsService(client, hooks, fetchPage, maxPages));
</file context>

[cubic-dev-ai]

P2: everythingFiles is paginated at runtime, but the declared return type is a plain array response alias. Using ListResult<...> in the signature preserves typed access to pagination metadata and matches the method’s actual return contract.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At typescript/src/generated/services/everything.ts, line 182:

<comment>`everythingFiles` is paginated at runtime, but the declared return type is a plain array response alias. Using `ListResult<...>` in the signature preserves typed access to pagination metadata and matches the method’s actual return contract.</comment>

<file context>
@@ -0,0 +1,273 @@
+   * const result = await client.everything.everythingFiles();
+   * ```
+   */
+  async everythingFiles(options?: EverythingFilesEverythingOptions): Promise<components["schemas"]["GetEverythingFilesResponseContent"]> {
+    return this.requestPaginated(
+      {
</file context>

[cubic-dev-ai]

P3: False API values are lost when callers marshal EverythingFile. Keep JSON tags on these response booleans without omitempty so false is represented.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At go/pkg/basecamp/everything.go, line 62:

<comment>False API values are lost when callers marshal `EverythingFile`. Keep JSON tags on these response booleans without `omitempty` so `false` is represented.</comment>

<file context>
@@ -0,0 +1,437 @@
+type EverythingFile struct {
+	ID               int64     `json:"id,omitempty"`
+	Status           string    `json:"status,omitempty"`
+	VisibleToClients bool      `json:"visible_to_clients,omitempty"`
+	CreatedAt        time.Time `json:"created_at,omitempty"`
+	UpdatedAt        time.Time `json:"updated_at,omitempty"`
</file context>

[cubic-dev-ai]

P3: Attachment variants with no timestamps serialize zero-time sentinels instead of preserving field absence. Use *time.Time for optional timestamps and populate them only when the generated value is present/non-zero.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At go/pkg/basecamp/everything.go, line 63:

<comment>Attachment variants with no timestamps serialize zero-time sentinels instead of preserving field absence. Use `*time.Time` for optional timestamps and populate them only when the generated value is present/non-zero.</comment>

<file context>
@@ -0,0 +1,437 @@
+	ID               int64     `json:"id,omitempty"`
+	Status           string    `json:"status,omitempty"`
+	VisibleToClients bool      `json:"visible_to_clients,omitempty"`
+	CreatedAt        time.Time `json:"created_at,omitempty"`
+	UpdatedAt        time.Time `json:"updated_at,omitempty"`
+	Title            string    `json:"title,omitempty"`
</file context>