Skip to content

Commit b2eca56

Browse files
dervondenbergendervondenbergen
committed
initial commit
TypeScript type definitions for the Didomi Web SDK. Provides Window interface augmentation for window.Didomi, window.didomiOnReady, window.didomiConfig, and window.__tcfapi.
0 parents  commit b2eca56

15 files changed

Lines changed: 1343 additions & 0 deletions

File tree

‎.claude/settings.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"WebFetch(domain:developers.didomi.io)",
5+
"WebFetch(domain:raw.githubusercontent.com)",
6+
"Update(index.d.ts)"
7+
]
8+
}
9+
}

‎.githooks/pre-commit‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
#!/bin/sh
2+
npm run typecheck

‎.github/workflows/ci.yml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
name: CI
2+
3+
on: [push, pull_request]
4+
5+
permissions:
6+
contents: read
7+
8+
jobs:
9+
typecheck:
10+
runs-on: ubuntu-slim
11+
steps:
12+
- uses: actions/checkout@v4
13+
- uses: actions/setup-node@v4
14+
with:
15+
node-version-file: .nvmrc
16+
- run: npm ci
17+
- run: npm run typecheck

‎.github/workflows/publish.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Publish
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
permissions:
8+
contents: read
9+
10+
jobs:
11+
typecheck:
12+
runs-on: ubuntu-slim
13+
steps:
14+
- uses: actions/checkout@v4
15+
- uses: actions/setup-node@v4
16+
with:
17+
node-version-file: .nvmrc
18+
- run: npm ci
19+
- run: npm run typecheck
20+
21+
publish:
22+
needs: typecheck
23+
runs-on: ubuntu-slim
24+
permissions:
25+
contents: read
26+
id-token: write
27+
steps:
28+
- uses: actions/checkout@v4
29+
- uses: actions/setup-node@v4
30+
with:
31+
node-version-file: .nvmrc
32+
registry-url: https://registry.npmjs.org
33+
- run: npm publish --provenance --access public

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
node_modules/
2+
.npmrc

‎.nvmrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
24

‎CLAUDE.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# @orfon/didomi-types
2+
3+
TypeScript type definitions for the Didomi Web SDK Window object augmentation.
4+
5+
## Update Types Task
6+
7+
When asked to update the types, check these resources for changes (in order of priority):
8+
9+
1. **Didomi Web SDK Documentation** (primary source of truth)
10+
- API Reference: https://developers.didomi.io/cmp/web-sdk/reference/api
11+
- Events Reference: https://developers.didomi.io/cmp/web-sdk/reference/events
12+
- Deprecated API: https://developers.didomi.io/cmp/web-sdk/reference/api/deprecated
13+
- Version History: https://developers.didomi.io/cmp/web-sdk/reference/versions
14+
15+
2. **Official Didomi GitHub Repositories** (secondary reference, may be outdated)
16+
- didomi-react: https://github.com/didomi/react (check `index.d.ts`)
17+
- didomi-react-native: https://github.com/didomi/react-native (check `src/DidomiTypes.ts`)
18+
19+
> **Note:** Prefer the SDK documentation over GitHub repositories when there are discrepancies, as the repos may not be up-to-date.
20+
21+
3. **Compare with current `index.d.ts`** and update:
22+
- New methods on `IDidomiObject`
23+
- New event types in `EventType`
24+
- Changes to `CurrentUserStatus`, `Vendor`, `Purpose` interfaces
25+
- New Window properties (`didomiOnReady`, `didomiConfig`, etc.)
26+
- TCF API changes
27+
28+
4. **Update `SOURCES.md`** after making changes to `index.d.ts`:
29+
- Update line number references if types moved
30+
- Add new sections for any new type categories
31+
- Document the source of any new types added
32+
- Remove sections for any deleted types
33+
34+
5. **Runtime Validation** (optional but recommended):
35+
- See `VALIDATION.md` for browser console commands to validate types
36+
- Ask the user to run validation commands and share the output
37+
- Compare runtime return types against type definitions
38+
39+
## Type Guidelines
40+
41+
- **Use only native TypeScript features** - No external libraries, utility types from packages, or non-standard TypeScript constructs
42+
- Types should work with any TypeScript version and not depend on specific compiler features
43+
44+
## Out of Scope
45+
46+
The following can be ignored when updating types:
47+
48+
- **Theming API** (`IThemeObject`, `theme` property) - Styling is handled via config, not relevant for type definitions
49+
- **`DidomiInitializeParameters`** - Native SDK initialization parameters from `didomi-react-native`, not applicable to Web SDK
50+
- **React Native specific types** - Only Web SDK types are maintained here
51+
52+
## Publishing
53+
54+
- Package is published to GitLab Package Registry
55+
- CI pipeline has a manual `publish` job
56+
- Bump version in `package.json` before publishing

‎LICENSE.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Modified BSD License (BSD-3)
2+
3+
_Copyright © `2026`, `dev.ORF.at`_
4+
_Portions derived from Didomi type definitions - Copyright © `2021`, `Didomi`_
5+
_All rights reserved._
6+
7+
Redistribution and use in source and binary forms, with or without
8+
modification, are permitted provided that the following conditions are met:
9+
10+
1. Redistributions of source code must retain the above copyright
11+
notice, this list of conditions and the following disclaimer.
12+
2. Redistributions in binary form must reproduce the above copyright
13+
notice, this list of conditions and the following disclaimer in the
14+
documentation and/or other materials provided with the distribution.
15+
3. Neither the name of `dev.ORF.at` or `Didomi` nor the
16+
names of its contributors may be used to endorse or promote products
17+
derived from this software without specific prior written permission.
18+
19+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
20+
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
21+
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22+
DISCLAIMED. IN NO EVENT SHALL `DEV.ORF.AT` OR `DIDOMI` BE LIABLE FOR ANY
23+
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24+
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25+
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
26+
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27+
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
28+
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎README.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# @orfon/didomi-types
2+
3+
TypeScript type definitions for the [Didomi Web SDK](https://developers.didomi.io/cmp/web-sdk/reference/api). This package augments the global `Window` interface so `window.Didomi`, `window.didomiOnReady`, `window.didomiConfig`, and `window.__tcfapi` are properly typed.
4+
5+
## Installation
6+
7+
```bash
8+
npm install @orfon/didomi-types --save-dev
9+
```
10+
11+
## Usage
12+
13+
After installing, the global `Window` interface is augmented automatically — no manual `import` needed for window properties.
14+
15+
### Typed `didomiOnReady` callback
16+
17+
The callback parameter is typed as `IDidomiObject`, so all SDK methods and their return types are available:
18+
19+
```typescript
20+
window.didomiOnReady = window.didomiOnReady || [];
21+
window.didomiOnReady.push((Didomi) => {
22+
// Didomi is typed as IDidomiObject
23+
// .getCurrentUserStatus() returns CurrentUserStatus
24+
const status = Didomi.getCurrentUserStatus();
25+
status.user_id; // string
26+
status.regulation; // string
27+
status.purposes; // Map<PurposeStatus>
28+
status.vendors; // Map<VendorStatus>
29+
});
30+
```
31+
32+
### Type-checked events
33+
34+
`EventType` is a string union — typos and invalid event names are caught at compile time:
35+
36+
```typescript
37+
window.didomiOnReady?.push((Didomi) => {
38+
Didomi.on('consent.changed', () => {}); // ok
39+
Didomi.on('notice.shown', () => {}); // ok
40+
Didomi.on('conset.changed', () => {}); // TS error: not assignable to EventType
41+
});
42+
```
43+
44+
### Importing types directly
45+
46+
You can import types for use in your own function signatures:
47+
48+
```typescript
49+
import type { CurrentUserStatus, Vendor, Purpose, EventType } from '@orfon/didomi-types';
50+
51+
function handleConsentChange(status: CurrentUserStatus): void {
52+
const enabledVendors = Object.values(status.vendors)
53+
.filter((v) => v.enabled);
54+
// ...
55+
}
56+
```
57+
58+
### Typed `didomiConfig`
59+
60+
Configuration is typed as `DidomiConfig`, giving you autocomplete and validation:
61+
62+
```typescript
63+
window.didomiConfig = {
64+
app: {
65+
apiKey: 'your-api-key',
66+
name: 'Your App',
67+
},
68+
languages: {
69+
enabled: ['en', 'de'],
70+
default: 'en',
71+
},
72+
};
73+
```
74+
75+
## Exported Types
76+
77+
The main types provided by this package:
78+
79+
| Type | Description |
80+
| --- | --- |
81+
| `IDidomiObject` | The main SDK object (`window.Didomi`) |
82+
| `CurrentUserStatus` | Return type of `getCurrentUserStatus()` |
83+
| `Vendor` / `VendorStatus` | Vendor definitions and consent status |
84+
| `Purpose` / `PurposeStatus` | Purpose definitions and consent status |
85+
| `EventType` | String union of all SDK event names |
86+
| `DidomiConfig` | Configuration object for `window.didomiConfig` |
87+
| `CurrentUserStatusTransaction` | Transaction for batch consent updates |
88+
| `TcfApi` | IAB TCF v2 API (`window.__tcfapi`) |
89+
90+
## License
91+
92+
[Modified BSD License (BSD-3)](LICENSE.md)

0 commit comments

Comments
 (0)