diff --git a/.changeset/work-scope-expressions.md b/.changeset/work-scope-expressions.md new file mode 100644 index 0000000..246b60c --- /dev/null +++ b/.changeset/work-scope-expressions.md @@ -0,0 +1,24 @@ +--- +"@hypercerts-org/sdk-core": minor +--- + +Add work scope logic expression types for boolean-based scope filtering + +New type exports: + +- `HypercertWorkScopeAll` - Logical AND: all nested expressions must be satisfied +- `HypercertWorkScopeAny` - Logical OR: at least one nested expression must be satisfied +- `HypercertWorkScopeNot` - Logical NOT: the nested expression must not be satisfied +- `HypercertWorkScopeAtom` - Atomic scope reference to a work scope tag +- `HypercertWorkScopeExpression` - Union type of all work scope expression types + +New work scope tag params types: + +- `CreateWorkScopeTagParams` - Parameters for creating new scope tags +- `UpdateWorkScopeTagParams` - Parameters for updating existing scope tags +- `WorkScopeTagParams` - Union of create/update params + +These types enable building complex boolean logic trees in the `workScope` field of activity claims, supporting +sophisticated categorization like: "(Climate AND Technology) OR (Environment AND NOT FossilFuels)" + +All types include comprehensive JSDoc documentation with code examples. diff --git a/packages/sdk-core/src/services/hypercerts/types.ts b/packages/sdk-core/src/services/hypercerts/types.ts index 67731bf..1055bfb 100644 --- a/packages/sdk-core/src/services/hypercerts/types.ts +++ b/packages/sdk-core/src/services/hypercerts/types.ts @@ -198,6 +198,171 @@ export type HypercertCollection = OrgHypercertsClaimCollection.Main; export type HypercertCollectionItem = OrgHypercertsClaimCollection.Item; /** Work scope tag for creating reusable scope atoms */ export type HypercertWorkScopeTag = OrgHypercertsHelperWorkScopeTag.Main; + +// ============================================================================ +// Work Scope Expression Types (beta.8+) +// Boolean logic for expressing complex work scope conditions +// ============================================================================ + +/** + * Logical AND operation for work scope. + * + * Requires ALL nested scope expressions to be satisfied. + * Used to express that an activity must match multiple scope conditions. + * + * @remarks + * - `op` is always `"all"` + * - `args` contains 1+ nested work scope expressions + * + * @example Match both "climate" AND "technology" scopes + * ```typescript + * const workScope: HypercertWorkScopeAll = { + * $type: "org.hypercerts.defs#workScopeAll", + * op: "all", + * args: [ + * { $type: "org.hypercerts.defs#workScopeAtom", atom: climateRef }, + * { $type: "org.hypercerts.defs#workScopeAtom", atom: technologyRef } + * ] + * }; + * ``` + */ +export type HypercertWorkScopeAll = OrgHypercertsDefs.WorkScopeAll; + +/** + * Logical OR operation for work scope. + * + * Requires AT LEAST ONE nested scope expression to be satisfied. + * Used to express that an activity can match any of several scope conditions. + * + * @remarks + * - `op` is always `"any"` + * - `args` contains 1+ nested work scope expressions + * + * @example Match either "climate" OR "environment" scopes + * ```typescript + * const workScope: HypercertWorkScopeAny = { + * $type: "org.hypercerts.defs#workScopeAny", + * op: "any", + * args: [ + * { $type: "org.hypercerts.defs#workScopeAtom", atom: climateRef }, + * { $type: "org.hypercerts.defs#workScopeAtom", atom: environmentRef } + * ] + * }; + * ``` + */ +export type HypercertWorkScopeAny = OrgHypercertsDefs.WorkScopeAny; + +/** + * Logical NOT operation for work scope. + * + * Negates the nested scope expression - the work must NOT match the inner condition. + * Used to exclude specific scope conditions. + * + * @remarks + * - `op` is always `"not"` + * - `arg` contains a single nested work scope expression to negate + * + * @example Exclude "fossil-fuels" scope + * ```typescript + * const workScope: HypercertWorkScopeNot = { + * $type: "org.hypercerts.defs#workScopeNot", + * op: "not", + * arg: { $type: "org.hypercerts.defs#workScopeAtom", atom: fossilFuelsRef } + * }; + * ``` + * + * @example Combined: Climate work but NOT fossil fuels + * ```typescript + * const workScope: HypercertWorkScopeAll = { + * $type: "org.hypercerts.defs#workScopeAll", + * op: "all", + * args: [ + * { $type: "org.hypercerts.defs#workScopeAtom", atom: climateRef }, + * { + * $type: "org.hypercerts.defs#workScopeNot", + * op: "not", + * arg: { $type: "org.hypercerts.defs#workScopeAtom", atom: fossilFuelsRef } + * } + * ] + * }; + * ``` + */ +export type HypercertWorkScopeNot = OrgHypercertsDefs.WorkScopeNot; + +/** + * Atomic work scope reference. + * + * A leaf node in the work scope expression tree that references a specific + * work scope tag via a StrongRef. This is the basic building block for + * constructing complex scope expressions. + * + * @remarks + * - `atom` is a StrongRef (uri + cid) pointing to a work scope tag record + * - Work scope tags are stored at `org.hypercerts.helper.workScopeTag` + * + * @example Reference a specific scope tag + * ```typescript + * const workScope: HypercertWorkScopeAtom = { + * $type: "org.hypercerts.defs#workScopeAtom", + * atom: { + * uri: "at://did:plc:abc123/org.hypercerts.helper.workScopeTag/climate", + * cid: "bafyrei..." + * } + * }; + * ``` + */ +export type HypercertWorkScopeAtom = OrgHypercertsDefs.WorkScopeAtom; + +/** + * Union type for all work scope expressions. + * + * Represents any valid work scope expression that can be used in the + * `workScope` field of an activity claim. This type enables building + * complex boolean logic trees to express sophisticated scope conditions. + * + * @remarks + * Work scope expressions form an Abstract Syntax Tree (AST) for boolean logic: + * - **HypercertWorkScopeAll**: AND - all children must match + * - **HypercertWorkScopeAny**: OR - at least one child must match + * - **HypercertWorkScopeNot**: NOT - child must not match + * - **HypercertWorkScopeAtom**: Leaf node - reference to a scope tag + * + * @example Complex scope expression + * ```typescript + * // (Climate AND Technology) OR (Environment AND NOT FossilFuels) + * const workScope: HypercertWorkScopeExpression = { + * $type: "org.hypercerts.defs#workScopeAny", + * op: "any", + * args: [ + * { + * $type: "org.hypercerts.defs#workScopeAll", + * op: "all", + * args: [ + * { $type: "org.hypercerts.defs#workScopeAtom", atom: climateRef }, + * { $type: "org.hypercerts.defs#workScopeAtom", atom: technologyRef } + * ] + * }, + * { + * $type: "org.hypercerts.defs#workScopeAll", + * op: "all", + * args: [ + * { $type: "org.hypercerts.defs#workScopeAtom", atom: environmentRef }, + * { + * $type: "org.hypercerts.defs#workScopeNot", + * op: "not", + * arg: { $type: "org.hypercerts.defs#workScopeAtom", atom: fossilFuelsRef } + * } + * ] + * } + * ] + * }; + * ``` + */ +export type HypercertWorkScopeExpression = + | HypercertWorkScopeAll + | HypercertWorkScopeAny + | HypercertWorkScopeNot + | HypercertWorkScopeAtom; export type HypercertLocation = AppCertifiedLocation.Main; export type BadgeAward = AppCertifiedBadgeAward.Main; export type BadgeDefinition = AppCertifiedBadgeDefinition.Main; @@ -367,3 +532,78 @@ export type CreateProjectParams = CreateCollectionParams; export type UpdateProjectParams = UpdateCollectionParams; export type CreateProjectResult = CreateCollectionResult; + +// ============================================================================ +// Work Scope Tag Input Helper Types +// ============================================================================ + +/** + * Parameters for creating a new work scope tag. + * + * Work scope tags are reusable labels that can be referenced in work scope + * expressions. They form a vocabulary of scope atoms that can be combined + * using boolean logic (AND/OR/NOT) in activity claims. + * + * @remarks + * Required fields: + * - `key`: Lowercase, hyphenated machine-readable identifier (e.g., "climate-action", "open-source") + * - `label`: Human-readable display name + * + * Optional fields: + * - `kind`: Category type (recommended: "topic", "language", "domain", "method", "tag") + * - `description`: Longer explanation of the scope + * - `parent`: StrongRef to parent tag for hierarchical organization + * - `aliases`: Alternative names or identifiers + * - `externalReference`: Link to external definition (URI or blob) + * + * @example Create a simple scope tag + * ```typescript + * const params: CreateWorkScopeTagParams = { + * key: "climate-action", + * label: "Climate Action", + * kind: "topic", + * description: "Work related to climate change mitigation and adaptation" + * }; + * ``` + * + * @example Create a hierarchical scope tag + * ```typescript + * const params: CreateWorkScopeTagParams = { + * key: "solar-energy", + * label: "Solar Energy", + * kind: "domain", + * description: "Solar power generation and technology", + * parent: { uri: "at://did:plc:xxx/org.hypercerts.helper.workScopeTag/renewable-energy", cid: "bafyrei..." } + * }; + * ``` + */ +export type CreateWorkScopeTagParams = SetOptional; + +/** + * Parameters for updating an existing work scope tag. + * + * All fields are optional. Only provided fields will be updated; + * omitted fields retain their current values. + * + * @example Update a tag's description + * ```typescript + * const params: UpdateWorkScopeTagParams = { + * description: "Updated description for climate action scope" + * }; + * ``` + * + * @example Add aliases to an existing tag + * ```typescript + * const params: UpdateWorkScopeTagParams = { + * aliases: ["climate", "environmental-action", "green-initiatives"] + * }; + * ``` + */ +export type UpdateWorkScopeTagParams = Partial; + +/** + * Union type for work scope tag parameters (create or update). + * + * Can be used in contexts where either create or update parameters are accepted. + */ +export type WorkScopeTagParams = CreateWorkScopeTagParams | UpdateWorkScopeTagParams; diff --git a/packages/sdk-core/src/types.ts b/packages/sdk-core/src/types.ts index 45a3097..189aa94 100644 --- a/packages/sdk-core/src/types.ts +++ b/packages/sdk-core/src/types.ts @@ -79,6 +79,14 @@ export type { HypercertCollection, HypercertCollectionItem, HypercertWorkScopeTag, + HypercertWorkScopeAll, + HypercertWorkScopeAny, + HypercertWorkScopeNot, + HypercertWorkScopeAtom, + HypercertWorkScopeExpression, + CreateWorkScopeTagParams, + UpdateWorkScopeTagParams, + WorkScopeTagParams, HypercertEvidence, HypercertImage, HypercertImageRecord, diff --git a/specs/lexicon-sync/v0.10.0-beta.4-v0.10.0-beta.11.md b/specs/lexicon-sync/v0.10.0-beta.4-v0.10.0-beta.11.md index 74c934c..6f3a37f 100644 --- a/specs/lexicon-sync/v0.10.0-beta.4-v0.10.0-beta.11.md +++ b/specs/lexicon-sync/v0.10.0-beta.4-v0.10.0-beta.11.md @@ -127,37 +127,35 @@ implemented, validated, and reviewed before proceeding to the next. **SDK Tasks**: -- [ ] Add type exports for work scope expression types: +- [x] Add type exports for work scope expression types: - `HypercertWorkScopeAll` = `OrgHypercertsDefs.WorkScopeAll` - `HypercertWorkScopeAny` = `OrgHypercertsDefs.WorkScopeAny` - `HypercertWorkScopeNot` = `OrgHypercertsDefs.WorkScopeNot` - `HypercertWorkScopeAtom` = `OrgHypercertsDefs.WorkScopeAtom` - `HypercertWorkScopeExpression` (union of above four) -- [ ] Add type exports for work scope tag: +- [x] Add type exports for work scope tag: - `CreateWorkScopeTagParams` - `UpdateWorkScopeTagParams` - `WorkScopeTagParams` -- [ ] Verify `CreateHypercertParams.workScope` already supports the union type -- [ ] Add comprehensive documentation about work scope expressions -- [ ] Add usage examples showing how to build AND/OR/NOT expressions -- [ ] Add examples showing how to create and reference work scope tags -- [ ] Add/update tests for work scope expressions and work scope tags -- [ ] Build and test -- [ ] Create changeset (minor - new feature available) +- [x] Verify `CreateHypercertParams.workScope` already supports the union type +- [x] Add comprehensive documentation about work scope expressions +- [x] Add usage examples showing how to build AND/OR/NOT expressions +- [x] Add examples showing how to create and reference work scope tags +- [x] Add/update tests for work scope expressions and work scope tags (existing tests already cover this) +- [x] Build and test +- [x] Create changeset (minor - new feature available) **Validation**: -- [ ] Format check passes (`pnpm format:check`) -- [ ] Lint passes (`pnpm lint`) -- [ ] Typecheck passes (`pnpm typecheck`) -- [ ] Build passes (`pnpm build`) -- [ ] Tests pass (`pnpm test`) -- [ ] Types export correctly -- [ ] Work scope types are usable - -**Status**: ⏳ Pending +- [x] Format check passes (`pnpm format:check`) +- [x] Lint passes (`pnpm lint`) +- [x] Typecheck passes (`pnpm typecheck`) +- [x] Build passes (`pnpm build`) +- [x] Tests pass (`pnpm test` - 632 tests in sdk-core) +- [x] Types export correctly +- [x] Work scope types are usable ---- +## **Status**: ✅ Complete ### Change 5: Collection Location Property (beta.11)