{"_id":"@apvee/m365-actionable-provisioning","name":"@apvee/m365-actionable-provisioning","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@apvee/m365-actionable-provisioning","version":"1.0.0","description":"Schema-first actionable provisioning engine for Microsoft 365, starting with SharePoint actions.","keywords":["m365","sharepoint","pnpjs","provisioning","actions","automation"],"license":"MIT","publishConfig":{"access":"public"},"main":"lib/index.js","types":"lib/index.d.ts","exports":{".":{"types":"./lib/index.d.ts","default":"./lib/index.js"},"./package.json":"./package.json"},"scripts":{"build":"npm run clean && tsc -p tsconfig.json","clean":"node -e \"require('fs').rmSync('lib', { recursive: true, force: true })\"","smoke:m365-engine":"tsx scripts/smoke-m365-engine.ts","prepack":"npm run build"},"dependencies":{"tslib":"2.3.1","zod":"^4.2.1"},"peerDependencies":{"@pnp/graph":"^4.17.0","@pnp/sp":"^4.17.0"},"devDependencies":{"@pnp/graph":"^4.17.0","@pnp/sp":"^4.17.0"},"_id":"@apvee/m365-actionable-provisioning@1.0.0","gitHead":"3ee971d5bfde889463afd8968cfa1661fc7408b8","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-qiYldkAtfLrse6v++CrLsTmqXwLBoXSv4E4/2yuWUIZLSnYrslgD7jBIqGY2zuGM/RxaoiK+qbr+WtK6gy1snA==","shasum":"fd7448e3a8607c1535634298cfe41fb3c2bd56d2","tarball":"https://registry.npmjs.org/@apvee/m365-actionable-provisioning/-/m365-actionable-provisioning-1.0.0.tgz","fileCount":548,"unpackedSize":6762876,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD9koI/Vc+8TQBadmAOQKY+aMpQF3KtGAxb97mEXnszngIhAJ3IOdnuHzjJqYNfHdZ3rqbpWiVIs5mfc5e2KTFxtso0"}]},"_npmUser":{"name":"fabiofranzini","email":"fabio@apvee.com"},"directories":{},"maintainers":[{"name":"fabiofranzini","email":"fabio@apvee.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/m365-actionable-provisioning_1.0.0_1782129359318_0.12367625002780414"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-22T11:55:59.054Z","1.0.0":"2026-06-22T11:55:59.487Z","modified":"2026-06-22T11:55:59.771Z"},"maintainers":[{"name":"fabiofranzini","email":"fabio@apvee.com"}],"description":"Schema-first actionable provisioning engine for Microsoft 365, starting with SharePoint actions.","keywords":["m365","sharepoint","pnpjs","provisioning","actions","automation"],"license":"MIT","readme":"# @apvee/m365-actionable-provisioning\n\nSchema-first actionable provisioning engine for Microsoft 365, starting with SharePoint actions.\n\n![@apvee/m365-actionable-provisioning](https://raw.githubusercontent.com/apvee/m365-actionable-provisioning/refs/heads/main/docs/m365-actionable-provisioning.jpeg)\n\nThis package contains the core runtime, the built-in Microsoft 365 provisioning catalog, Zod schemas, logging utilities, compliance checks, and SharePoint action definitions. It does not contain SPFx React UI. Use `@apvee/spfx-m365-actionable-provisioning` for SPFx components, hooks, property pane fields, and localization.\n\n## Installation\n\n```bash\nnpm install @apvee/m365-actionable-provisioning @pnp/sp @pnp/graph\n```\n\n`@pnp/sp` and `@pnp/graph` are peer dependencies because host applications own their authenticated PnPjs clients.\n\n## Public API\n\nThe npm package exposes only the package root (`@apvee/m365-actionable-provisioning`) and `./package.json`. Import public APIs from the package root; deep import paths are not part of the package export contract.\n\nThe package root exports these public areas:\n\n- `core`: generic provisioning engine, action definitions, compliance types, permissions, logging, and tracing.\n- `runtime`: Microsoft 365 client, scope, context, and lightweight result types.\n- `catalog`: built-in M365 provisioning catalog, `createM365ProvisioningEngine`, and provisioning plan schema/types.\n- `actions/sharepoint`: SharePoint action schemas, definitions, modules, and action-specific payload types.\n\nPrefer `createM365ProvisioningEngine` for the built-in catalog. Construct `ProvisioningEngine` directly only when you need to replace the action definitions or provisioning schema.\n\n## Quick Start\n\n```typescript\nimport {\n  createLogger,\n  createM365ProvisioningEngine,\n  consoleSink,\n  type M365ProvisioningPlan,\n} from '@apvee/m365-actionable-provisioning';\n\nconst plan: M365ProvisioningPlan = {\n  schemaVersion: '1.0',\n  parameters: [\n    { key: 'SiteUrl', value: 'https://contoso.sharepoint.com/sites/engineering' },\n  ],\n  actions: [\n    {\n      verb: 'modifySPSite',\n      siteUrl: '{parameter:SiteUrl}',\n      title: 'Engineering Portal',\n      subactions: [\n        {\n          verb: 'createSPList',\n          listName: 'requests',\n          title: 'Requests',\n          template: 100,\n          subactions: [\n            {\n              verb: 'addSPField',\n              fieldType: 'Text',\n              fieldName: 'RequestTitle',\n              displayName: 'Request Title',\n              required: true,\n            },\n          ],\n        },\n      ],\n    },\n  ],\n};\n\nconst engine = createM365ProvisioningEngine({\n  clients: { spfi, graphClient },\n  initialScope: { web: targetWeb, siteUrl: 'https://contoso.sharepoint.com/sites/engineering' },\n  planTemplate: plan,\n  logger: createLogger({ level: 'info', sink: consoleSink }),\n});\n\nconst snapshot = await engine.run();\nconst report = await engine.checkCompliance();\n```\n\n## Runtime Clients And Scope\n\nClients are injected once when the engine is created and are available to actions through `ctx.clients`:\n\n```typescript\ntype M365Clients = {\n  spfi?: SPFI;\n  graphClient?: GraphFI;\n};\n```\n\nRuntime scope is reserved for propagated handles and identifiers such as `site`, `web`, `list`, `graphSiteId`, `graphListId`, `siteUrl`, `webUrl`, `listName`, `contentTypeId`, `contentTypeName`, and `siteColumnIdsByFieldName`.\n\n## SharePoint Action Placement\n\n| Placement | Verbs |\n| --- | --- |\n| Root | `createSPSite`, `modifySPSite`, `deleteSPSite`, `createSPList`, `modifySPList`, `deleteSPList`, `createSPContentType`, `modifySPContentType`, `deleteSPContentType` |\n| Site subaction | `createSPList`, `modifySPList`, `deleteSPList`, `createSPNavigationNode`, `modifySPNavigationNode`, `deleteSPNavigationNode`, `breakSPSiteRoleInheritance`, `resetSPSiteRoleInheritance`, `grantSPSiteRoleAssignment`, `removeSPSiteRoleAssignment`, `createSPContentType`, `modifySPContentType`, `deleteSPContentType`, `createSPSiteColumn`, `modifySPField`, `deleteSPField` |\n| List subaction | `addSPField`, `modifySPField`, `deleteSPField`, `enableSPListRating`, `createSPListView`, `modifySPListView`, `deleteSPListView`, `breakSPListRoleInheritance`, `resetSPListRoleInheritance`, `grantSPListRoleAssignment`, `removeSPListRoleAssignment`, `addSPContentTypeToList`, `removeSPContentTypeFromList` |\n| Content type subaction | `addSPFieldToContentType`, `modifySPContentTypeField`, `removeSPFieldFromContentType` |\n\nUse `addSPField` for list fields and `createSPSiteColumn` for site columns.\n\n## Action Semantics\n\nProvisioning actions use explicit semantics:\n\n- `create*` actions ensure a resource exists.\n- `modify*` actions enforce mutable desired state.\n- `delete*` actions ensure a resource is absent.\n\nCreate actions are intentionally idempotent and tolerant. If a resource already exists with the same stable identity, the action may return `skipped` with `reason: \"already_exists\"` and continue. Mutable properties supplied to create actions, such as titles, descriptions, groups, required flags, versioning settings, or default values, are create-time defaults. They are not reconciled when the resource already exists.\n\nUse a follow-up `modify*` action when a plan must enforce mutable state:\n\n```typescript\n{\n  verb: 'createSPList',\n  listName: 'requests',\n  title: 'Requests',\n},\n{\n  verb: 'modifySPList',\n  listName: 'requests',\n  title: 'Richieste',\n  enableVersioning: true,\n}\n```\n\nCreate actions may still report structural warnings or non-compliant compliance results for collisions that make the plan ambiguous, such as an existing field with the requested internal name but a different SharePoint field type.\n\n`listName` always means the stable SharePoint list root/name, not the mutable list title or Graph display name.\n\n## Content Types And Graph Permissions\n\nContent type actions are Graph-first and require `graphClient`.\n\nConsumer applications must configure Microsoft Graph `Sites.Manage.All` or a higher permission such as `Sites.FullControl.All` when they use content type actions. SPFx packages typically need:\n\n```json\n\"webApiPermissionRequests\": [\n  {\n    \"resource\": \"Microsoft Graph\",\n    \"scope\": \"Sites.Manage.All\"\n  }\n]\n```\n\nThe engine does not inspect token claims. Missing Graph clients are caught during preflight. Insufficient Graph permissions are reported when Graph returns `401` or `403`.\n\n## Compliance And Warnings\n\nCall `checkCompliance()` to compare the current Microsoft 365 state with a plan without making changes. Compliance for create actions checks existence and structural compatibility; it does not fail because mutable properties differ unless the collision makes descendant actions unsafe or ambiguous.\n\nAction results may include `warnings`. Warnings are non-blocking audit details used when an action succeeds or skips but part of the operation needs operator attention.\n\n## Package Scripts\n\n```bash\nnpm run build -w @apvee/m365-actionable-provisioning\nnpm run smoke:m365-engine -w @apvee/m365-actionable-provisioning\n```\n\n## Deeper Documentation\n\n- [Introduction](../../docs/introduction.md)\n- [Core engine](../../docs/core/engine.md)\n- [Provisioning schema](../../docs/core/provisioning-schema.md)\n- [SPFx integration package](../../docs/spfx/integration.md)\n- [SharePoint action catalog notes](./src/actions/sharepoint/ACTIONS.md)\n- [Adding SharePoint actions](./src/actions/sharepoint/ADDING_ACTIONS.md)\n","readmeFilename":"README.md","_rev":"1-af0e57fa6bd0881761af1e5dace5ea92"}