@artsy/cohesion 4.370.0 → 4.371.0
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.
- package/AGENTS.md +132 -0
- package/CHANGELOG.md +12 -0
- package/CLAUDE.md +3 -0
- package/package.json +1 -1
package/AGENTS.md
ADDED
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Agent Guidelines
|
|
2
|
+
|
|
3
|
+
`@artsy/cohesion` is **Artsy's analytics schema** — a published TypeScript package of
|
|
4
|
+
interfaces and enums that describe every analytics event sent to Segment/Redshift.
|
|
5
|
+
There is no runtime logic: each event is a typed shape, and each event name maps to a
|
|
6
|
+
downstream Redshift table. Consuming apps (web + iOS) import these types to fire events.
|
|
7
|
+
|
|
8
|
+
## Tech Stack
|
|
9
|
+
|
|
10
|
+
- **TypeScript** (strict) — the entire schema is type definitions; no runtime code
|
|
11
|
+
- **Babel** — compiles `src/**/*.ts` → `dist/` (`@babel/preset-typescript`)
|
|
12
|
+
- **tsc** — type-checking and `.d.ts` emission only (not used for transpiling)
|
|
13
|
+
- **Jest** — tests assert each event interface serializes to its expected JSON shape
|
|
14
|
+
- **ESLint + Prettier** — `simple-import-sort` and `sort-keys-fix` are enforced
|
|
15
|
+
- **TypeDoc** — public docs at https://cohesion.artsy.net are generated from doc comments
|
|
16
|
+
- **Auto / CircleCI** — versioning and npm publish on merge to `main`
|
|
17
|
+
|
|
18
|
+
## Common Commands
|
|
19
|
+
|
|
20
|
+
- `yarn test` — run the Jest suite (`<file>` or `-t <name>` to scope)
|
|
21
|
+
- `yarn type-check` — `tsc --noEmit` (also runs on pre-push)
|
|
22
|
+
- `yarn lint` — `eslint . --ext .ts --fix` (import + key sorting)
|
|
23
|
+
- `yarn docs` — regenerate TypeDoc output into `doc/`
|
|
24
|
+
|
|
25
|
+
## Pre-Commit Verification
|
|
26
|
+
|
|
27
|
+
Before every commit, verify on pending files:
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
yarn type-check
|
|
31
|
+
yarn test
|
|
32
|
+
yarn lint
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
`husky` runs `lint-staged` on pre-commit and `yarn type-check` on pre-push. Never commit
|
|
36
|
+
code that fails these checks.
|
|
37
|
+
|
|
38
|
+
## Code Style & Common Patterns
|
|
39
|
+
|
|
40
|
+
These are enforced by lint/test or are established conventions — follow them verbatim:
|
|
41
|
+
|
|
42
|
+
- **One interface per event.** Name it `UpperCamelCase`; its `action` literal and the
|
|
43
|
+
matching `ActionType`/`OsActionType` enum member are `lowerCamelCase`. The enum member
|
|
44
|
+
value **is** the Redshift table name, so it must not change casually.
|
|
45
|
+
- **`action` is always a literal type**, e.g. `action: ActionType.commercialFilterParamsChanged`
|
|
46
|
+
(not the bare `ActionType`).
|
|
47
|
+
- **Sort keys alphabetically.** `sort-keys-fix` lints interface members, enum members, and
|
|
48
|
+
object literals (including test fixtures) into alphabetical order. Run `yarn lint` to fix.
|
|
49
|
+
- **Sort imports.** `simple-import-sort` orders imports; let `--fix` handle it.
|
|
50
|
+
- **Every event needs a context module and an owner type.** Use `context_module`
|
|
51
|
+
(`ContextModule`/`OsContextModule`) for the component, and an owner-type field for the
|
|
52
|
+
page/screen: `context_owner_type` (`OwnerType`), or `context_page_owner_type` /
|
|
53
|
+
`context_screen_owner_type` for the page/screen-scoped subtypes.
|
|
54
|
+
- **Document every event with a TypeDoc block** containing a prose description and an
|
|
55
|
+
`@example` code fence showing the emitted JSON. This is the public documentation — see
|
|
56
|
+
`src/Schema/Events/FilterAndSort.ts` for the canonical style.
|
|
57
|
+
- **Aggregate interfaces into a union** (e.g. `OsSubmitEvent`, `OsEvent`) and re-export
|
|
58
|
+
every new file from the relevant `index.ts` and `src/Schema/index.ts`.
|
|
59
|
+
- **Prettier:** no semicolons, double quotes, trailing commas, 2-space indent.
|
|
60
|
+
|
|
61
|
+
To add a CMS or core event, follow the step-by-step guide in [README.md](README.md#schema).
|
|
62
|
+
|
|
63
|
+
## ArtOS Events (`src/Schema/os/`)
|
|
64
|
+
|
|
65
|
+
ArtOS events have their **own** schema and conventions — do **not** reuse CMS or core
|
|
66
|
+
events for ArtOS. When adding ArtOS tracking, follow these principles (from the
|
|
67
|
+
[ArtOS tracking guidelines](https://app.notion.com/p/373cab0764a080fca7e7d5a984ec17c7) and
|
|
68
|
+
[Filter/Sort/Search doc](https://app.notion.com/p/37bcab0764a081a2b22dc0f6434e44fa)):
|
|
69
|
+
|
|
70
|
+
1. **Live under `src/Schema/os/`** with its own `Events/` and `Values/` folders. ArtOS has
|
|
71
|
+
dedicated `OsActionType`, `OsContextModule`, and `OsOwnerType` — never the shared ones.
|
|
72
|
+
2. **Never reuse CMS events** for ArtOS surfaces, and vice versa.
|
|
73
|
+
3. **Name events `VerbNoun`, past tense** — `ClickedFilterDrawer`, `CreatedStudioContent`,
|
|
74
|
+
`BulkEditedArtworks`. (The older `NounVerb` names like `ListCreated` were flipped.)
|
|
75
|
+
4. **No generic action events.** Avoid `InventoryClicked` / `Clicked` / `Toggled` /
|
|
76
|
+
`Impression`; events must name the specific intent (`ClickedActionsDropdown`,
|
|
77
|
+
not a catch-all click). Events should be **reusable across surfaces** by intent — e.g.
|
|
78
|
+
`ClickedFilterDrawer` can fire on any page that has a filter component.
|
|
79
|
+
5. **Differentiate surfaces via owner type, not a module field.** Do not add an `OSModule`
|
|
80
|
+
field; use `context_page_owner_type` (`inventory`, `collection`, `studioInstagram`, …)
|
|
81
|
+
to distinguish ArtOS surfaces. The URL itself changes (`/catalog` → `/lists` → …).
|
|
82
|
+
6. **Group reusable events by interaction in shared files** (`Click.ts`, `Impression.ts`,
|
|
83
|
+
`Toggle.ts`). A set of events that is 100% non-reusable and scoped to one surface may get
|
|
84
|
+
its own file (e.g. `InstagramEditor.ts`, `MultiAddFlow.ts`).
|
|
85
|
+
7. **Backend-tied, flow-completion events go in `Submit.ts`** — events that fire on
|
|
86
|
+
successful completion of a flow and depend on a backend change (`BulkEditedArtworks`,
|
|
87
|
+
`DeletedArtwork`, `DistributedArtworks`). These are platform-agnostic (web + future app),
|
|
88
|
+
so they stay out of the web-only `Click.ts`.
|
|
89
|
+
8. **Avoid name collisions with existing events** — the OS list events drop the "Artwork"
|
|
90
|
+
qualifier (`CreatedList`, not `CreatedArtworkList`) so they don't clash with the existing
|
|
91
|
+
CMS saved-artwork-list events.
|
|
92
|
+
|
|
93
|
+
## File Organization
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
src/
|
|
97
|
+
├── index.ts # Top-level package entry (re-exports Schema + DeprecatedHelpers)
|
|
98
|
+
├── Schema/
|
|
99
|
+
│ ├── index.ts # Re-exports every event + value file (web/iOS, CMS, ArtOS)
|
|
100
|
+
│ ├── Events/ # Core web + iOS events (FilterAndSort, Search, Click, Tap, …)
|
|
101
|
+
│ ├── Values/ # Shared enums: ContextModule, OwnerType, Intent, Tab, …
|
|
102
|
+
│ ├── CMS/ # CMS (gallery partner CMS) schema — Events/ + Values/
|
|
103
|
+
│ └── os/ # ArtOS schema — see "ArtOS Events" above
|
|
104
|
+
│ ├── Events/ # Click, Submit, InstagramEditor, MultiAddFlow, … (+ __tests__/)
|
|
105
|
+
│ └── Values/ # OsContextModule, OsOwnerType
|
|
106
|
+
├── DeprecatedSchema/ # Frozen legacy schema — do not extend
|
|
107
|
+
└── DeprecatedHelpers/ # Frozen legacy helpers — do not extend
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## Workflow
|
|
111
|
+
|
|
112
|
+
- Branch off `main`; open a PR using `pull_request_template.md`.
|
|
113
|
+
- Merging to `main` auto-publishes a new npm version via Auto; **PRs from feature branches
|
|
114
|
+
publish canary versions** consumers can test before merge.
|
|
115
|
+
- Commit messages follow Conventional Commits (e.g. `chore:`, `feat:`) — used by Auto to
|
|
116
|
+
decide the version bump.
|
|
117
|
+
|
|
118
|
+
## Gotchas
|
|
119
|
+
|
|
120
|
+
- **Adding a file is not enough** — it must be re-exported from `src/Schema/index.ts` (and
|
|
121
|
+
any folder `index.ts` union) or consumers can't import it.
|
|
122
|
+
- **The enum value is a contract.** An `ActionType`/`OsActionType` value names a Redshift
|
|
123
|
+
table; renaming it breaks the downstream data pipeline.
|
|
124
|
+
- **`DeprecatedSchema` / `DeprecatedHelpers` are frozen** — add new events to `Schema`.
|
|
125
|
+
- **Doc comments are shipped docs**, not just hints — keep `@example` blocks accurate.
|
|
126
|
+
- The data team owns the core `Schema`; coordinate before changing shared `Values`.
|
|
127
|
+
|
|
128
|
+
## Further Documentation
|
|
129
|
+
|
|
130
|
+
- [README.md](README.md) — setup, and the canonical "add a new event" walkthrough
|
|
131
|
+
- ArtOS tracking guidelines: [event list & principles](https://app.notion.com/p/373cab0764a080fca7e7d5a984ec17c7), [Filter/Sort/Search](https://app.notion.com/p/37bcab0764a081a2b22dc0f6434e44fa)
|
|
132
|
+
- Generated API docs: https://cohesion.artsy.net
|
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,15 @@
|
|
|
1
|
+
# v4.371.0 (Fri Jun 26 2026)
|
|
2
|
+
|
|
3
|
+
#### 🚀 Enhancement
|
|
4
|
+
|
|
5
|
+
- chore: Add AGENTS.md and CLAUDE.md for agent onboarding [#715](https://github.com/artsy/cohesion/pull/715) ([@MounirDhahri](https://github.com/MounirDhahri))
|
|
6
|
+
|
|
7
|
+
#### Authors: 1
|
|
8
|
+
|
|
9
|
+
- Mounir Dhahri ([@MounirDhahri](https://github.com/MounirDhahri))
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
1
13
|
# v4.370.0 (Thu Jun 25 2026)
|
|
2
14
|
|
|
3
15
|
#### 🚀 Enhancement
|
package/CLAUDE.md
ADDED