@salesforce/afv-skills 1.19.0 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [

package/skills/dx-app-analytics-use/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: dx-app-analytics-use
+description: "ISV App Analytics metadata types — AppAnalyticsQueryRequest and AppAnalyticsSettings. Use this skill when the user asks about retrieving managed package usage data, configuring App Analytics simulation mode, querying subscriber snapshots, or understanding the AppAnalyticsQueryRequest lifecycle (New → Pending → Complete → Expired). TRIGGER when: user mentions App Analytics, AppAnalyticsQueryRequest, AppAnalyticsSettings, package usage data, subscriber analytics, ISV analytics, or simulation mode for app analytics. DO NOT TRIGGER when: the task is about standard Salesforce reports/dashboards (use reporting skills), custom SOQL on Account/Contact (use querying-soql), or Data Cloud query/search (use retrieving-datacloud)."
+metadata:
+  version: "1.0"
+  minApiVersion: "56.0"
+---
+
+# App Analytics
+
+## When This Skill Owns the Task
+
+Use `dx-app-analytics-use` when the work involves:
+- Creating `AppAnalyticsQueryRequest` records via the REST/sObject API
+- Configuring `AppAnalyticsSettings` via the Metadata API (simulation mode, opt-out)
+- Understanding the query lifecycle: New → Pending → Complete → Expired → Failed
+- Choosing between dataType values: PackageUsageSummary, PackageUsageLog, SubscriberSnapshot
+- File format and compression options for analytics downloads
+- Time-range filtering with startTime, endTime, availableSince
+- Troubleshooting failed or expired analytics queries
+
+Delegate elsewhere when the user is:
+- Running standard CRM SOQL queries → querying-soql
+- Working with Data Cloud SQL or DMOs → retrieving-datacloud
+- Building reports/dashboards on standard objects → reporting skills
+- Deploying or retrieving generic metadata XML → deploying-metadata / retrieving-metadata
+
+---
+
+## Available Types
+
+### AppAnalyticsQueryRequest (REST/sObject API)
+
+An asynchronous query request that ISV partners use to retrieve usage analytics data for their managed packages from the ISV Intelligence Data Lake. Records are created via `POST /services/data/vXX.0/sobjects/AppAnalyticsQueryRequest` and polled via `GET /services/data/vXX.0/sobjects/AppAnalyticsQueryRequest/<id>`. The system processes the query and provides a presigned download URL upon completion.
+
+**Fields (14 properties):**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| DataType | string (filterable) | Type of analytics data. Values: `PackageUsageSummary`, `PackageUsageLog`, `SubscriberSnapshot` |
+| RequestState | string (filterable) | Processing status. Values: `New`, `Pending`, `Complete`, `Expired`, `Failed`, `NoData`, `Delivered` |
+| StartTime | string | Start of time range for requested data |
+| EndTime | string | End of time range. Should be set on an hour boundary |
+| AvailableSince | string | Limits query to data indexed after this time (inclusive). Use for incremental retrieval |
+| PackageIds | string | Comma-delimited list of managed package IDs (033-prefix) |
+| OrganizationIds | string | Comma-delimited list of subscriber org IDs to filter results |
+| DownloadUrl | string | Presigned URL for downloading results. Populated when RequestState is Complete |
+| DownloadSize | long | Size in bytes of the result data file |
+| DownloadExpirationTime | string | Time at which the download URL expires |
+| FileType | string (filterable) | Output format. Values: `csv`, `parquet` |
+| FileCompression | string (filterable) | Compression. Values: `none`, `gzip`, `snappy` |
+| QuerySubmittedTime | string | Time the query was submitted to the Data Lake |
+| ErrorMessage | string | Diagnostic message for failed queries |
+
+### AppAnalyticsSettings (Metadata API)
+
+Configuration settings for ISV App Analytics that control simulation mode and opt-out behavior. Deployed via the Metadata API (`sf project deploy`) or Tooling API.
+
+**Fields (2 properties):**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| enableSimulationMode | boolean (filterable) | When true, allows querying sample usage logs for integration testing without real subscriber data |
+| enableAppAnalyticsOptOut | boolean (filterable) | When true, opts this subscriber org out of AppExchange App Analytics data collection |
+
+---
+
+## Request Lifecycle
+
+```text
+New → Pending → Complete → (download within expiration window)
+                         → Expired (download URL no longer valid)
+                         → Delivered (download confirmed received)
+         → Failed (check errorMessage)
+         → NoData (no matching records for the criteria)
+```
+
+---
+
+## Common Patterns
+
+### Query Package Usage Summary (last 7 days)
+
+Create a record via the REST API:
+
+```bash
+POST /services/data/v60.0/sobjects/AppAnalyticsQueryRequest
+Content-Type: application/json
+
+{
+  "DataType": "PackageUsageSummary",
+  "StartTime": "<7-days-ago>T00:00:00Z",
+  "EndTime": "<today-on-hour-boundary>T00:00:00Z",
+  "PackageIds": "033XXXXXXXXXXXX",
+  "FileType": "csv",
+  "FileCompression": "gzip"
+}
+```
+
+Poll the record via GET until `RequestState` reaches `Complete`, then download from `DownloadUrl`.
+
+### Incremental Data Retrieval
+
+Set `AvailableSince` to the timestamp of your last successful query completion to avoid re-downloading data you already have.
+
+### Enable Simulation Mode for Testing
+
+Deploy `AppAnalyticsSettings` via Metadata API with `enableSimulationMode: true` to query sample data without real subscribers.
+
+---
+
+## High-Signal Gotchas
+
+- AppAnalyticsQueryRequest is an **sObject** — create and poll records via the REST Data API (`/sobjects/AppAnalyticsQueryRequest`), NOT via Metadata API XML deployment.
+- AppAnalyticsQueryRequest does NOT have Apex triggers and does NOT flow through custom objects or Flows.
+- Download URLs expire — always check `DownloadExpirationTime` before attempting download.
+- `EndTime` should be set on an hour boundary for consistent results.
+- `AvailableSince` is inclusive — data indexed at exactly that timestamp will be included.
+- `PackageIds` uses 033-prefix IDs, not 04t (package version) IDs.
+- Data is processed asynchronously by the ISV Intelligence Data Lake infrastructure. There is no synchronous query option.
+- `FileType: parquet` with `FileCompression: snappy` gives optimal performance for large datasets.
+
+---
+
+## Output Format
+
+```text
+Analytics task: <query / configure / troubleshoot>
+Data type: <PackageUsageSummary / PackageUsageLog / SubscriberSnapshot>
+Package IDs: <033-prefixed IDs>
+Time range: <startTime> to <endTime>
+File format: <csv|parquet> / <none|gzip|snappy>
+Request state: <current state>
+Next step: <poll for completion / download / investigate failure>
+```

package/skills/platform-agentexchange-partner-offers-enable/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: platform-agentexchange-partner-offers-enable
+description: "Enable or disable the org preference that controls whether a Salesforce org can receive partner offers from the Transactable Marketplace. Use this skill when the user wants to turn partner offer reception on or off for an org. TRIGGER when: user asks to enable or disable partner offers, configure TransactableMarketplaceReceivePartnerOffers, configure enableTransactableMarketplaceReceivePartnerOffers, set up marketplace partner offer reception, toggle the TM partner offers setting, edit a TransactableMarketplacePrivateOffer.settings file, or configure org preferences related to transactable marketplace. DO NOT TRIGGER when: user needs to create or manage the partner offer records themselves, configure marketplace listing settings, or work with SfdcPartnerOffer objects (use deploying-metadata or generating-apex instead)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Enabling Transactable Marketplace Receive Partner Offers Org Preference
+
+This skill configures the `enableTransactableMarketplaceReceivePartnerOffers` org preference via the `TransactableMarketplacePrivateOfferSettings` Metadata API type, which controls whether a Salesforce org is eligible to receive partner offers through the Transactable Marketplace. It is required for subscriber orgs that participate in the TM partner offer flow.
+
+## Scope
+
+- **In scope**: Reading the current value of the pref, enabling or disabling it via Metadata API (`TransactableMarketplacePrivateOfferSettings`), and verifying the change took effect.
+- **Out of scope**: Creating or managing partner offer records, configuring marketplace listings, or any Apex/trigger changes related to offer processing.
+
+---
+
+## Required Inputs
+
+- **Target org alias or username**: The org where the pref should be set. Ask if not provided.
+- **Desired state**: `true` (enable) or `false` (disable). Default: `true`.
+
+---
+
+## Workflow
+
+### Phase 1 — Check current state
+
+1. **Query the current preference value** by running:
+   ```bash
+   sf data query -q "SELECT Preference, Value FROM OrgPreference WHERE Preference = 'TransactableMarketplaceReceivePartnerOffers'" --target-org <alias> --use-tooling-api
+   ```
+   If the record exists and `Value = true`, the pref is already enabled — confirm with the user before proceeding.
+   If the query returns no rows, the pref is not yet set (defaults to `false`).
+
+2. **Resolve the org's package directory** to determine where to write metadata. Run this and use its output as `<packageDir>`:
+   ```bash
+   jq -r '.packageDirectories[0].path // "force-app/main/default"' sfdx-project.json
+   ```
+
+### Phase 2 — Apply the preference
+
+3. **Write the TransactableMarketplacePrivateOfferSettings metadata file** — load `assets/org-pref-template.md` for the exact XML structure, then write the file at:
+   ```text
+   <packageDir>/settings/TransactableMarketplacePrivateOffer.settings
+   ```
+   Set `<enableTransactableMarketplaceReceivePartnerOffers>true</enableTransactableMarketplaceReceivePartnerOffers>` (or `false` if disabling).
+
+4. **Deploy the metadata** to the target org. Before running the deploy, confirm with the user:
+   - [ ] Confirmed the target org alias with the user (deploying to the wrong org is not easily reversible)
+   - [ ] Confirmed the desired state (`true`/`false`) matches the user's intent
+   ```bash
+   sf project deploy start --metadata TransactableMarketplacePrivateOfferSettings --target-org <alias>
+   ```
+
+### Phase 3 — Verify
+
+5. **Confirm the change** by re-running the Tooling API query from step 1 and verifying the `Value` column matches the desired state.
+
+6. **Report to the user** — see Output Expectations below.
+
+---
+
+## Rules / Constraints
+
+| Rule | Rationale |
+|------|-----------|
+| Always query the current value before writing metadata | Avoids unnecessary deploys and detects conflicting changes |
+| Use `TransactableMarketplacePrivateOfferSettings` as the metadata type | This is the concrete type registered in the platform for this pref, not the generic `OrgPreferenceSettings` |
+| The settings file must be named `TransactableMarketplacePrivateOffer.settings` | Metadata API requires the filename to match the settings node name |
+| Do not hardcode `force-app/main/default/` | Always read `sfdx-project.json` for the actual package directory |
+| Never deploy without confirming the org alias with the user | Deploying to the wrong org is not easily reversible |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| Tooling API query returns no rows | Pref is unset (defaults to `false`). Safe to create a new settings file. |
+| Deploy fails with `INVALID_TYPE` | The metadata type name is `TransactableMarketplacePrivateOfferSettings` — check the `--metadata` flag value. |
+| Deploy succeeds but value doesn't change | Another settings file in the project may be overriding this one. Search for other `TransactableMarketplacePrivateOffer.settings` files in the project. |
+| `INSUFFICIENT_ACCESS_OR_READONLY` on deploy | User running the deploy must have the "Modify All Data" or org preference admin permission in the target org. |
+| Pref not visible in UI | `enableTransactableMarketplaceReceivePartnerOffers` is not surfaced in Setup UI — the Tooling API query is the only way to verify it. |
+| Available from API version 67.0+ only | The type is available from API v67.0 — deploying against an older API version will fail. |
+
+---
+
+## Output Expectations
+
+After completing all phases, report:
+
+```text
+Org: <alias>
+Preference: enableTransactableMarketplaceReceivePartnerOffers
+Previous value: <true|false|unset>
+New value: <true|false>
+File written: <packageDir>/settings/TransactableMarketplacePrivateOffer.settings
+Deploy status: Success
+```
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `assets/org-pref-template.md` | Phase 2, step 3 — use as the exact XML structure for the settings file |
+| `examples/org-preference-settings.xml` | To verify the generated file matches expected format |

package/skills/platform-agentexchange-partner-offers-enable/assets/org-pref-template.md

@@ -0,0 +1,27 @@
+# TransactableMarketplacePrivateOfferSettings XML Template
+
+Use this exact structure when writing the settings metadata file.
+
+## File path
+
+```text
+<packageDir>/settings/TransactableMarketplacePrivateOffer.settings
+```
+
+## Template
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<TransactableMarketplacePrivateOfferSettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <enableTransactableMarketplaceReceivePartnerOffers>true</enableTransactableMarketplaceReceivePartnerOffers>
+</TransactableMarketplacePrivateOfferSettings>
+```
+
+Replace `true` with `false` to disable.
+
+## Notes
+
+- The metadata type is `TransactableMarketplacePrivateOfferSettings`, available from API version 67.0+.
+- This type is registered with `apiCreateAllowed="false"` and `apiDeleteAllowed="false"` — it can only be updated, not created or deleted via the API. This does NOT mean you should skip writing the file: the preference always exists in the org with a default value, so writing a new local settings file and deploying it is treated as an update by the Metadata API and is always valid.
+- The `xmlns` attribute is required; omitting it causes a deploy parse error.
+- The field name is `enableTransactableMarketplaceReceivePartnerOffers` (note the `enable` prefix).

package/skills/platform-agentexchange-partner-offers-enable/examples/org-preference-settings.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<TransactableMarketplacePrivateOfferSettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <enableTransactableMarketplaceReceivePartnerOffers>true</enableTransactableMarketplaceReceivePartnerOffers>
+</TransactableMarketplacePrivateOfferSettings>