Skip to content

Commit 2a9ac0d

Browse files
s-adamantineaspiers
s-adamantine
authored and
aspiers
committed
feat(sdk-core): add work scope logic expression types
Add type exports for work scope boolean expressions (beta.8): - HypercertWorkScopeAll: Logical AND operation - HypercertWorkScopeAny: Logical OR operation - HypercertWorkScopeNot: Logical NOT operation - HypercertWorkScopeAtom: Atomic scope reference - HypercertWorkScopeExpression: Union of all expression types Add work scope tag params types: - CreateWorkScopeTagParams - UpdateWorkScopeTagParams - WorkScopeTagParams Includes comprehensive JSDoc documentation with code examples demonstrating how to build complex boolean scope expressions.
1 parent 3b9e014 commit 2a9ac0d

4 files changed

Lines changed: 289 additions & 19 deletions

File tree

‎.changeset/work-scope-expressions.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
"@hypercerts-org/sdk-core": minor
3+
---
4+
5+
Add work scope logic expression types for boolean-based scope filtering
6+
7+
New type exports:
8+
9+
- `HypercertWorkScopeAll` - Logical AND: all nested expressions must be satisfied
10+
- `HypercertWorkScopeAny` - Logical OR: at least one nested expression must be satisfied
11+
- `HypercertWorkScopeNot` - Logical NOT: the nested expression must not be satisfied
12+
- `HypercertWorkScopeAtom` - Atomic scope reference to a work scope tag
13+
- `HypercertWorkScopeExpression` - Union type of all work scope expression types
14+
15+
New work scope tag params types:
16+
17+
- `CreateWorkScopeTagParams` - Parameters for creating new scope tags
18+
- `UpdateWorkScopeTagParams` - Parameters for updating existing scope tags
19+
- `WorkScopeTagParams` - Union of create/update params
20+
21+
These types enable building complex boolean logic trees in the `workScope` field of activity claims, supporting
22+
sophisticated categorization like: "(Climate AND Technology) OR (Environment AND NOT FossilFuels)"
23+
24+
All types include comprehensive JSDoc documentation with code examples.

‎packages/sdk-core/src/services/hypercerts/types.ts‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,6 +198,171 @@ export type HypercertCollection = OrgHypercertsClaimCollection.Main;
198198
export type HypercertCollectionItem = OrgHypercertsClaimCollection.Item;
199199
/** Work scope tag for creating reusable scope atoms */
200200
export type HypercertWorkScopeTag = OrgHypercertsHelperWorkScopeTag.Main;
201+
202+
// ============================================================================
203+
// Work Scope Expression Types (beta.8+)
204+
// Boolean logic for expressing complex work scope conditions
205+
// ============================================================================
206+
207+
/**
208+
* Logical AND operation for work scope.
209+
*
210+
* Requires ALL nested scope expressions to be satisfied.
211+
* Used to express that an activity must match multiple scope conditions.
212+
*
213+
* @remarks
214+
* - `op` is always `"all"`
215+
* - `args` contains 1+ nested work scope expressions
216+
*
217+
* @example Match both "climate" AND "technology" scopes
218+
* ```typescript
219+
* const workScope: HypercertWorkScopeAll = {
220+
* $type: "org.hypercerts.defs#workScopeAll",
221+
* op: "all",
222+
* args: [
223+
* { $type: "org.hypercerts.defs#workScopeAtom", atom: climateRef },
224+
* { $type: "org.hypercerts.defs#workScopeAtom", atom: technologyRef }
225+
* ]
226+
* };
227+
* ```
228+
*/
229+
export type HypercertWorkScopeAll = OrgHypercertsDefs.WorkScopeAll;
230+
231+
/**
232+
* Logical OR operation for work scope.
233+
*
234+
* Requires AT LEAST ONE nested scope expression to be satisfied.
235+
* Used to express that an activity can match any of several scope conditions.
236+
*
237+
* @remarks
238+
* - `op` is always `"any"`
239+
* - `args` contains 1+ nested work scope expressions
240+
*
241+
* @example Match either "climate" OR "environment" scopes
242+
* ```typescript
243+
* const workScope: HypercertWorkScopeAny = {
244+
* $type: "org.hypercerts.defs#workScopeAny",
245+
* op: "any",
246+
* args: [
247+
* { $type: "org.hypercerts.defs#workScopeAtom", atom: climateRef },
248+
* { $type: "org.hypercerts.defs#workScopeAtom", atom: environmentRef }
249+
* ]
250+
* };
251+
* ```
252+
*/
253+
export type HypercertWorkScopeAny = OrgHypercertsDefs.WorkScopeAny;
254+
255+
/**
256+
* Logical NOT operation for work scope.
257+
*
258+
* Negates the nested scope expression - the work must NOT match the inner condition.
259+
* Used to exclude specific scope conditions.
260+
*
261+
* @remarks
262+
* - `op` is always `"not"`
263+
* - `arg` contains a single nested work scope expression to negate
264+
*
265+
* @example Exclude "fossil-fuels" scope
266+
* ```typescript
267+
* const workScope: HypercertWorkScopeNot = {
268+
* $type: "org.hypercerts.defs#workScopeNot",
269+
* op: "not",
270+
* arg: { $type: "org.hypercerts.defs#workScopeAtom", atom: fossilFuelsRef }
271+
* };
272+
* ```
273+
*
274+
* @example Combined: Climate work but NOT fossil fuels
275+
* ```typescript
276+
* const workScope: HypercertWorkScopeAll = {
277+
* $type: "org.hypercerts.defs#workScopeAll",
278+
* op: "all",
279+
* args: [
280+
* { $type: "org.hypercerts.defs#workScopeAtom", atom: climateRef },
281+
* {
282+
* $type: "org.hypercerts.defs#workScopeNot",
283+
* op: "not",
284+
* arg: { $type: "org.hypercerts.defs#workScopeAtom", atom: fossilFuelsRef }
285+
* }
286+
* ]
287+
* };
288+
* ```
289+
*/
290+
export type HypercertWorkScopeNot = OrgHypercertsDefs.WorkScopeNot;
291+
292+
/**
293+
* Atomic work scope reference.
294+
*
295+
* A leaf node in the work scope expression tree that references a specific
296+
* work scope tag via a StrongRef. This is the basic building block for
297+
* constructing complex scope expressions.
298+
*
299+
* @remarks
300+
* - `atom` is a StrongRef (uri + cid) pointing to a work scope tag record
301+
* - Work scope tags are stored at `org.hypercerts.helper.workScopeTag`
302+
*
303+
* @example Reference a specific scope tag
304+
* ```typescript
305+
* const workScope: HypercertWorkScopeAtom = {
306+
* $type: "org.hypercerts.defs#workScopeAtom",
307+
* atom: {
308+
* uri: "at://did:plc:abc123/org.hypercerts.helper.workScopeTag/climate",
309+
* cid: "bafyrei..."
310+
* }
311+
* };
312+
* ```
313+
*/
314+
export type HypercertWorkScopeAtom = OrgHypercertsDefs.WorkScopeAtom;
315+
316+
/**
317+
* Union type for all work scope expressions.
318+
*
319+
* Represents any valid work scope expression that can be used in the
320+
* `workScope` field of an activity claim. This type enables building
321+
* complex boolean logic trees to express sophisticated scope conditions.
322+
*
323+
* @remarks
324+
* Work scope expressions form an Abstract Syntax Tree (AST) for boolean logic:
325+
* - **HypercertWorkScopeAll**: AND - all children must match
326+
* - **HypercertWorkScopeAny**: OR - at least one child must match
327+
* - **HypercertWorkScopeNot**: NOT - child must not match
328+
* - **HypercertWorkScopeAtom**: Leaf node - reference to a scope tag
329+
*
330+
* @example Complex scope expression
331+
* ```typescript
332+
* // (Climate AND Technology) OR (Environment AND NOT FossilFuels)
333+
* const workScope: HypercertWorkScopeExpression = {
334+
* $type: "org.hypercerts.defs#workScopeAny",
335+
* op: "any",
336+
* args: [
337+
* {
338+
* $type: "org.hypercerts.defs#workScopeAll",
339+
* op: "all",
340+
* args: [
341+
* { $type: "org.hypercerts.defs#workScopeAtom", atom: climateRef },
342+
* { $type: "org.hypercerts.defs#workScopeAtom", atom: technologyRef }
343+
* ]
344+
* },
345+
* {
346+
* $type: "org.hypercerts.defs#workScopeAll",
347+
* op: "all",
348+
* args: [
349+
* { $type: "org.hypercerts.defs#workScopeAtom", atom: environmentRef },
350+
* {
351+
* $type: "org.hypercerts.defs#workScopeNot",
352+
* op: "not",
353+
* arg: { $type: "org.hypercerts.defs#workScopeAtom", atom: fossilFuelsRef }
354+
* }
355+
* ]
356+
* }
357+
* ]
358+
* };
359+
* ```
360+
*/
361+
export type HypercertWorkScopeExpression =
362+
| HypercertWorkScopeAll
363+
| HypercertWorkScopeAny
364+
| HypercertWorkScopeNot
365+
| HypercertWorkScopeAtom;
201366
export type HypercertLocation = AppCertifiedLocation.Main;
202367
export type BadgeAward = AppCertifiedBadgeAward.Main;
203368
export type BadgeDefinition = AppCertifiedBadgeDefinition.Main;
@@ -367,3 +532,78 @@ export type CreateProjectParams = CreateCollectionParams;
367532
export type UpdateProjectParams = UpdateCollectionParams;
368533

369534
export type CreateProjectResult = CreateCollectionResult;
535+
536+
// ============================================================================
537+
// Work Scope Tag Input Helper Types
538+
// ============================================================================
539+
540+
/**
541+
* Parameters for creating a new work scope tag.
542+
*
543+
* Work scope tags are reusable labels that can be referenced in work scope
544+
* expressions. They form a vocabulary of scope atoms that can be combined
545+
* using boolean logic (AND/OR/NOT) in activity claims.
546+
*
547+
* @remarks
548+
* Required fields:
549+
* - `key`: Lowercase, hyphenated machine-readable identifier (e.g., "climate-action", "open-source")
550+
* - `label`: Human-readable display name
551+
*
552+
* Optional fields:
553+
* - `kind`: Category type (recommended: "topic", "language", "domain", "method", "tag")
554+
* - `description`: Longer explanation of the scope
555+
* - `parent`: StrongRef to parent tag for hierarchical organization
556+
* - `aliases`: Alternative names or identifiers
557+
* - `externalReference`: Link to external definition (URI or blob)
558+
*
559+
* @example Create a simple scope tag
560+
* ```typescript
561+
* const params: CreateWorkScopeTagParams = {
562+
* key: "climate-action",
563+
* label: "Climate Action",
564+
* kind: "topic",
565+
* description: "Work related to climate change mitigation and adaptation"
566+
* };
567+
* ```
568+
*
569+
* @example Create a hierarchical scope tag
570+
* ```typescript
571+
* const params: CreateWorkScopeTagParams = {
572+
* key: "solar-energy",
573+
* label: "Solar Energy",
574+
* kind: "domain",
575+
* description: "Solar power generation and technology",
576+
* parent: { uri: "at://did:plc:xxx/org.hypercerts.helper.workScopeTag/renewable-energy", cid: "bafyrei..." }
577+
* };
578+
* ```
579+
*/
580+
export type CreateWorkScopeTagParams = SetOptional<HypercertWorkScopeTag, "$type" | "createdAt">;
581+
582+
/**
583+
* Parameters for updating an existing work scope tag.
584+
*
585+
* All fields are optional. Only provided fields will be updated;
586+
* omitted fields retain their current values.
587+
*
588+
* @example Update a tag's description
589+
* ```typescript
590+
* const params: UpdateWorkScopeTagParams = {
591+
* description: "Updated description for climate action scope"
592+
* };
593+
* ```
594+
*
595+
* @example Add aliases to an existing tag
596+
* ```typescript
597+
* const params: UpdateWorkScopeTagParams = {
598+
* aliases: ["climate", "environmental-action", "green-initiatives"]
599+
* };
600+
* ```
601+
*/
602+
export type UpdateWorkScopeTagParams = Partial<CreateWorkScopeTagParams>;
603+
604+
/**
605+
* Union type for work scope tag parameters (create or update).
606+
*
607+
* Can be used in contexts where either create or update parameters are accepted.
608+
*/
609+
export type WorkScopeTagParams = CreateWorkScopeTagParams | UpdateWorkScopeTagParams;

‎packages/sdk-core/src/types.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,14 @@ export type {
7979
HypercertCollection,
8080
HypercertCollectionItem,
8181
HypercertWorkScopeTag,
82+
HypercertWorkScopeAll,
83+
HypercertWorkScopeAny,
84+
HypercertWorkScopeNot,
85+
HypercertWorkScopeAtom,
86+
HypercertWorkScopeExpression,
87+
CreateWorkScopeTagParams,
88+
UpdateWorkScopeTagParams,
89+
WorkScopeTagParams,
8290
HypercertEvidence,
8391
HypercertImage,
8492
HypercertImageRecord,

‎specs/lexicon-sync/v0.10.0-beta.4-v0.10.0-beta.11.md‎

Lines changed: 17 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -127,37 +127,35 @@ implemented, validated, and reviewed before proceeding to the next.
127127

128128
**SDK Tasks**:
129129

130-
- [ ] Add type exports for work scope expression types:
130+
- [x] Add type exports for work scope expression types:
131131
- `HypercertWorkScopeAll` = `OrgHypercertsDefs.WorkScopeAll`
132132
- `HypercertWorkScopeAny` = `OrgHypercertsDefs.WorkScopeAny`
133133
- `HypercertWorkScopeNot` = `OrgHypercertsDefs.WorkScopeNot`
134134
- `HypercertWorkScopeAtom` = `OrgHypercertsDefs.WorkScopeAtom`
135135
- `HypercertWorkScopeExpression` (union of above four)
136-
- [ ] Add type exports for work scope tag:
136+
- [x] Add type exports for work scope tag:
137137
- `CreateWorkScopeTagParams`
138138
- `UpdateWorkScopeTagParams`
139139
- `WorkScopeTagParams`
140-
- [ ] Verify `CreateHypercertParams.workScope` already supports the union type
141-
- [ ] Add comprehensive documentation about work scope expressions
142-
- [ ] Add usage examples showing how to build AND/OR/NOT expressions
143-
- [ ] Add examples showing how to create and reference work scope tags
144-
- [ ] Add/update tests for work scope expressions and work scope tags
145-
- [ ] Build and test
146-
- [ ] Create changeset (minor - new feature available)
140+
- [x] Verify `CreateHypercertParams.workScope` already supports the union type
141+
- [x] Add comprehensive documentation about work scope expressions
142+
- [x] Add usage examples showing how to build AND/OR/NOT expressions
143+
- [x] Add examples showing how to create and reference work scope tags
144+
- [x] Add/update tests for work scope expressions and work scope tags (existing tests already cover this)
145+
- [x] Build and test
146+
- [x] Create changeset (minor - new feature available)
147147

148148
**Validation**:
149149

150-
- [ ] Format check passes (`pnpm format:check`)
151-
- [ ] Lint passes (`pnpm lint`)
152-
- [ ] Typecheck passes (`pnpm typecheck`)
153-
- [ ] Build passes (`pnpm build`)
154-
- [ ] Tests pass (`pnpm test`)
155-
- [ ] Types export correctly
156-
- [ ] Work scope types are usable
157-
158-
**Status**: ⏳ Pending
150+
- [x] Format check passes (`pnpm format:check`)
151+
- [x] Lint passes (`pnpm lint`)
152+
- [x] Typecheck passes (`pnpm typecheck`)
153+
- [x] Build passes (`pnpm build`)
154+
- [x] Tests pass (`pnpm test` - 632 tests in sdk-core)
155+
- [x] Types export correctly
156+
- [x] Work scope types are usable
159157

160-
---
158+
## **Status**: ✅ Complete
161159

162160
### Change 5: Collection Location Property (beta.11)
163161

0 commit comments

Comments
 (0)