ClientCraft.Sdk 1.0.0-preview.14

Client Craft SDK

Server-side .NET 10 integration. This preview is not a release attestation.

Do not publish the captured preview.11: malformed binding responses can omit state/status and deserialize to defaults. The successor requires explicit response fields and authoritative state/version pairs; its immutable consumer qualification remains required. Existing preview.11 checks did not cover this newly confirmed defect. Original archives remain preserved.

The extracted Core source composer registers the SDK. Core remains a partial internal candidate; installing this standalone SDK does not install Umbraco, Core, the Visual Builder or a browser interface. Existing uCRM installations retain their existing package until the replacement upgrade is qualified.

The frozen security-corrected candidate is 1.0.0-preview.12; its exact-package consumer passed48selected SDK cases. Development source is 1.0.0-preview.14 and contains additional contracts that are not in that frozen archive. The rejected preview.11 and its older passing checks remain historical evidence. The immutable preview.13 capture is preserved. It predates the current one-time workload-token contract: retries/recovery return metadata without the bearer. Do not treat that capture as qualified for the updated workload protocol. The immutable local preview.9 package passed native API compatibility validation against public 1.0.0-preview.5 without suppressions. Its website contract qualification recorded 31 passing cases, 20 additional passing scope cases and 3 corrected cancellation scenarios. These are focused selections, not full-project release qualification. The failed preview.6 archive and the initial three cancellation failures remain historical evidence.

No new monorepo package has been publicly published. Never overwrite a local or published package version. Release qualification and explicit publication approval through the protected release workflow remain required.

Register with services.AddClientCraft(configuration.GetSection("uCRM")) and inject IClientCraftClient. Configuration accepts TenantId (or the existing TenantIdentifier / Tenant alias), IntegrationKey and CrmApiBaseUrl. Store credentials in a secret provider, never browser code or source control.

The configured identity is the credential owner. Selecting a resource workspace does not grant access: the API checks the credential, hierarchy and permissions. Interactive actor context comes from a trusted server adapter, never browser headers. A standalone machine client does not invent an interactive actor.

Creation requires a stable idempotency key supplied by the caller. Updates require the record version returned by the API. An accepted asynchronous request does not mean its background operation finished.

UpdateAsync uses the API's full-record PUT contract: send the complete editable state you intend to preserve, not a partial patch. Archive uses the reviewed version; restoration also requires a stable idempotency key. All authorization, quota checks and replay decisions remain API-owned.

This candidate currently implements CRM lead/contact/company list, read, create, update and archive/restore, plus lead-company association. Forms, booking, imports, agency onboarding and generated reference transport are not yet included.

Trusted host connection providers

IClientCraftConnectionProvider resolves a server-only immutable connection snapshot. Register a provider with AddClientCraft<MyConnectionProvider>() when credentials come from a host-managed secret provider. AddClientCraft<MyConnectionProvider>(configuration) keeps explicit tenant/key configuration authoritative and uses the host provider only when all credential settings are absent. Empty or partial explicit settings fail; they never select a different stored identity.

The configuration adapter captures a connection for each DI scope. Rotation appears in the next scope without changing requests already using the previous snapshot. Create a scope per background operation, and supply its authorized workspace explicitly. Providers must preserve that same request-snapshot behavior and honor cancellation. Registering a provider does not implement persistence, authorize a tenant, or grant an acting person permission. Automatic file/secret-store onboarding is not yet shipped.

client.Tenancy exposes connection discovery, current workspace, capabilities and the existing workspace directory APIs. ForWorkspace(id) retains the credential owner. Directory presence and IsPlatformRoot are metadata, not authorization. CanEnter defaults to false when an older API omits that capability. The current directory limit is an explicit API conflict, not a silently truncated complete list.

client.Tenancy.ResolveMembershipsAsync(workspaceIds) reads the acting person's memberships through the existing API contract. Supply the verified actor through the trusted context provider (or IClientCraftClientFactory.Create(connection, actorId)), never from an unverified browser field. Selecting a workspace does not change that actor or the credential. The SDK validates identifiers and sends once; rejection does not create membership or trigger an automatic retry. API authorization remains final.

Operational transport uses the resolved origin, credential and deadline together; pooled HTTP handlers never retain tenant credentials. Connection diagnostic strings and JSON serialization omit the integration key. Do not serialize configuration or other server objects into public responses.

Optional Website observation capabilities (development source)

client.WebsiteAnalytics() exposes server-side observation correlation through an optional provider interface, preserving existing custom IClientCraftClient implementations. Unsupported custom capabilities fail explicitly. Business outcomes, recording and heatmap transports are separate optional capabilities. Selecting a workspace retains the configured credential and trusted actor.

Native consent proofs and correlation handles remain server-side references; they are not visitor consent, API authorization, confirmed conversions or CRM mutation authority. Transport validates bounded payloads, protocol versions and response acknowledgements. Central API authorization remains final. Do not put proofs, workload credentials or connection configuration into browser content. The standalone SDK does not install a collector or consent interface.

These development contracts passed87focused executable transport scenarios with synthetic HTTP responses. Real collector/API operation and a new immutable package release remain unqualified. See docs/compatibility/ANALYTICS-SDK-20261018.md in the source repository.

Purchases and protected administration

client.Purchases.ForSeller(sellerId) exposes offers, begin, checkout, status, claim, activation, discovery, resume and reviewed invitation/intent operations. Use a server-selected purchase connection from IClientCraftClientFactory; seller selection never replaces its credential. Retain purchase IDs and proof values through recovery. There are no automatic mutation retries. Verified email/user arguments must originate from the authenticated server workflow.

client.Administration is a separate compatibility interface for existing approved administration routes. It requires a verified actor and pins the request to the connection owner, even after ForWorkspace. Supply the dedicated administration connection; never substitute an ordinary or purchase key. Responses preserve HTTP status and bounded payloads so existing authorization/validation responses survive. The API still decides authority; SDK route validation is not an authorization grant.

Hosts with several isolated credentials can register AddClientCraftTransport() and use the factory without registering a default credential/context provider. Operational secrets stay on the server. These additions are source implementations; release qualification and migration of other capabilities remain in progress.

Installation bootstrap without tenant credentials

Register AddClientCraftTransport() and call factory.CreateInstallationOnboarding(trustedApiOrigin) to obtain the separate IInstallationOnboardingClient. This flow sends the installation ownership proof, never the configured tenant integration key, actor or workspace headers. It cannot perform ordinary CRM operations. The API origin comes from trusted host configuration.

Persist the ownership session, claim ID/proof and prepared activation candidate in the selected server secret provider before issuing commands. The SDK exposes ownership verification, connection status and the existing managed/prepared exchange contracts; it neither approves a connection nor provisions a tenant on its own. Preserve proofs and IDs on recovery; commands are sent once, with bounded responses and no redirect following. Automatic activation returns status only. The legacy credential exchange is for the explicitly authorized administrator-managed configuration flow.

Workspace setup

IClientCraftClientFactory.CreateInstallationOnboarding(trustedApiOrigin) supports ownership verification, explicit installation connections and the existing create-workspace, plans, checkout, checkout-status, billing-history and managed credential-handoff contracts. It uses no configured tenant key. Keep InstallationSession and credential results on the server. API ownership, purchase activation and administrator checks remain authoritative. The SDK does not automatically retry checkout, provisioning, renewal or credential issuance. RenewVerificationAsync retains an existing pending/approved claim after fresh identity verification; the API rejects changed identities, stale session transitions, active and revoked connections. Automatic prepared activation remains separate from manual credential handoff.

Customer-approved agency assistance

client.Tenancy.AgencyAccess exposes paginated requests, decisions, revocation and decision history. Create the client with the verified staff identity. Request access from the agency workspace; review and decide from the customer's workspace as a direct customer administrator. Directory visibility does not constitute consent.

Keep request IDs, operation IDs and reviewed versions stable across a lost response. Decisions require a reason and cannot increase the requested permissions or duration. Supported durations are one_hour, four_hours (default), 24_hours and ongoing. Ongoing duration does not add permissions. Revocation preserves the decision history. The ordinary client deliberately exposes no platform-override method.

This consent contract is under release qualification. It does not by itself replace legacy workspace-entry authorization: API enforcement, package access controls and the customer approval UI must be qualified together before agency cutover.

CRM summaries, duplicate checks and view preferences

client.Crm.Operations exposes the existing attention/collection summaries, Lead, Contact and Company duplicate suggestions, and the acting person's saved view state. Use ForWorkspace(authorizedWorkspace) to target an explicitly selected workspace; the server connection still owns its credential and the API checks access.

// Inject IClientCraftClient with a server-side verified actor/context provider.
var operations = client.ForWorkspace(authorizedWorkspace).Crm.Operations;
var attention = await operations.GetAttentionSummaryAsync(cancellationToken);
var suggestions = await operations.FindContactDuplicatesAsync(email, phone, cancellationToken);
var saved = await operations.SaveViewPreferenceAsync("contacts", "list",
    new("{\"columns\":[\"name\",\"email\"]}"), cancellationToken);

Duplicate results are suggestions, never automatic record selection or merging. A missing saved view remains a 404; access denial remains distinct. The SDK sends preference updates once and does not retry an uncertain response. This API stores current view state, not user-created/shareable saved-view definitions. Its existing last-write behavior is unchanged; no concurrency guarantee is invented by the SDK.

The preview.10 source adds explicit activation, activation-receipt and online Active Website context methods. Existing custom readers reject these optional methods by default. The actual SDK transport passed29focused contract cases, including3executable Gherkin wire scenarios, with no failed/skipped tests; scoped project coverage16.76%line/24.47%branch remains below release gates. These machine metadata operations confer no human, operational workload or offline authority. No preview.10 archive or native consumer release is qualified by those source tests alone.