apply namechanges

Author: Mohammod Al Amin Ashik

.changeset/deprecate-resources-touchpoints-core.md

@@ -0,0 +1,27 @@
+---
+'@sitecore-marketplace-sdk/core': patch
+---
+
+Deprecate `resources` and `touchpoints` properties in favor of `resourceAccess` and `extensionsPoints`
+
+**BREAKING CHANGE (Deprecation):**
+
+- The `resources` property in `ApplicationContext` and `ApplicationRuntimeContext` interfaces is now deprecated. Use `resourceAccess` instead.
+- The `touchpoints` property in `ApplicationContext` and `ApplicationRuntimeContext` interfaces is now deprecated. Use `extensionsPoints` instead.
+
+**What changed:**
+
+- Added deprecation JSDoc comments to `resources` and `touchpoints` properties in both interfaces
+- Added new `resourceAccess` and `extensionsPoints` properties to `ApplicationContext` and `ApplicationRuntimeContext` interfaces
+- Maintained backward compatibility - deprecated properties still work but will show deprecation warnings in IDEs
+
+**Migration guide:**
+
+Replace usage of deprecated properties with their new equivalents:
+
+- `applicationContext.resources` → `applicationContext.resourceAccess`
+- `applicationContext.touchpoints` → `applicationContext.extensionsPoints`
+- `runtimeContext.resources` → `runtimeContext.resourceAccess`
+- `runtimeContext.touchpoints` → `runtimeContext.extensionsPoints`
+
+The deprecated properties will be removed in a future major version.

.changeset/update-readme-resourceaccess-client.md

@@ -0,0 +1,21 @@
+---
+'@sitecore-marketplace-sdk/client': patch
+---
+
+Update README documentation to use new `resourceAccess` property name
+
+**What changed:**
+
+- Updated README.md examples to use `resourceAccess` instead of the deprecated `resources` property
+- Updated descriptive text to refer to "resource access" instead of "resources" for consistency with new property naming
+- Improved code examples and documentation to reflect the current recommended API usage
+- Enhanced initialization examples with comprehensive React hooks and error handling patterns
+
+**Migration guide:**
+
+When following the README examples, use:
+
+- `applicationContext.resourceAccess` instead of `applicationContext.resources` in your code
+- The examples now demonstrate best practices for SDK initialization and usage
+
+This change ensures developers following the documentation will use the recommended property names from the start.

packages/client/README.md

@@ -3,15 +3,17 @@
 The `client` package provides secure, bidirectional communication between a Marketplace application (the client) and Sitecore (the host). Sitecore loads the Marketplace app inside a sandboxed [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe). The iframe and its parent window securely communicate using the web browser's [PostMessage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).
 
 This package lets you:
+
 - Make queries. Queries support one-off data requests and subscriptions for live updates. The `client` package lets you query the host's state and environment, and the [context](#query-the-application-context) of your Marketplace app.
 - Make mutations. Mutations trigger state changes or HTTP requests in Sitecore.
-- Interact with Sitecore APIs to perform actions on behalf of the resources it was granted access to during installation.
+- Interact with Sitecore APIs to perform actions on behalf of the resource access it was granted during installation.
   > [!TIP]
   > Inspired by GraphQL and React Query, the query/mutation API manages internal state, loading status, and error handling.
 
 The `client` package is required for all Marketplace apps.
 
 ## Prerequisites
+
 - Node.js 16 or later. Check your installed version by using the `node --version` command.
 - npm 10 or later. Check your installed version by using the `npm --version` command.
 - Access to the Sitecore Cloud Portal.
@@ -31,8 +33,8 @@ Before you use queries or mutations, you must initialize the Client SDK.
 ```typescript
 // utils/hooks/useMarketplaceClient.ts
 
-import { ClientSDK } from "@sitecore-marketplace-sdk/client";
-import { useEffect, useState, useCallback, useMemo, useRef } from "react";
+import { ClientSDK } from '@sitecore-marketplace-sdk/client';
+import { useEffect, useState, useCallback, useMemo, useRef } from 'react';
 
 export interface MarketplaceClientState {
   client: ClientSDK | null;
@@ -84,9 +86,7 @@ async function getMarketplaceClient() {
 
 export function useMarketplaceClient(options: UseMarketplaceClientOptions = {}) {
   // Memoize the options to prevent unnecessary re-renders
-  const opts = useMemo(() => ({ ...DEFAULT_OPTIONS, ...options }), [
-    options,
-  ]);
+  const opts = useMemo(() => ({ ...DEFAULT_OPTIONS, ...options }), [options]);
 
   const [state, setState] = useState<MarketplaceClientState>({
     client: null,
@@ -98,44 +98,48 @@ export function useMarketplaceClient(options: UseMarketplaceClientOptions = {})
   // Use ref to track if we're currently initializing to prevent race conditions
   const isInitializingRef = useRef(false);
 
-  const initializeClient = useCallback(async (attempt = 1): Promise<void> => {
-    // Use functional state update to check current state without dependencies
-    let shouldProceed = false;
-    setState(prev => {
-      if (prev.isLoading || prev.isInitialized || isInitializingRef.current) {
-        return prev;
-      }
-      shouldProceed = true;
-      isInitializingRef.current = true;
-      return { ...prev, isLoading: true, error: null };
-    });
+  const initializeClient = useCallback(
+    async (attempt = 1): Promise<void> => {
+      // Use functional state update to check current state without dependencies
+      let shouldProceed = false;
+      setState((prev) => {
+        if (prev.isLoading || prev.isInitialized || isInitializingRef.current) {
+          return prev;
+        }
+        shouldProceed = true;
+        isInitializingRef.current = true;
+        return { ...prev, isLoading: true, error: null };
+      });
 
-    if (!shouldProceed) return;
+      if (!shouldProceed) return;
 
-    try {
-      const client = await getMarketplaceClient();
-      setState({
-        client,
-        error: null,
-        isLoading: false,
-        isInitialized: true,
-      });
-    } catch (error) {
-      if (attempt < opts.retryAttempts) {
-        await new Promise(resolve => setTimeout(resolve, opts.retryDelay));
-        return initializeClient(attempt + 1);
+      try {
+        const client = await getMarketplaceClient();
+        setState({
+          client,
+          error: null,
+          isLoading: false,
+          isInitialized: true,
+        });
+      } catch (error) {
+        if (attempt < opts.retryAttempts) {
+          await new Promise((resolve) => setTimeout(resolve, opts.retryDelay));
+          return initializeClient(attempt + 1);
+        }
+
+        setState({
+          client: null,
+          error:
+            error instanceof Error ? error : new Error('Failed to initialize MarketplaceClient'),
+          isLoading: false,
+          isInitialized: false,
+        });
+      } finally {
+        isInitializingRef.current = false;
       }
-
-      setState({
-        client: null,
-        error: error instanceof Error ? error : new Error('Failed to initialize MarketplaceClient'),
-        isLoading: false,
-        isInitialized: false,
-      });
-    } finally {
-      isInitializingRef.current = false;
-    }
-  }, [opts.retryAttempts, opts.retryDelay]); // Removed state dependencies
+    },
+    [opts.retryAttempts, opts.retryDelay],
+  ); // Removed state dependencies
 
   useEffect(() => {
     if (opts.autoInit) {
@@ -154,14 +158,18 @@ export function useMarketplaceClient(options: UseMarketplaceClientOptions = {})
   }, [opts.autoInit, initializeClient]);
 
   // Memoize the return value to prevent object recreation on every render
-  return useMemo(() => ({
-    ...state,
-    initialize: initializeClient,
-  }), [state, initializeClient]);
+  return useMemo(
+    () => ({
+      ...state,
+      initialize: initializeClient,
+    }),
+    [state, initializeClient],
+  );
 }
 ```
 
 2. Initialize the SDK:
+
 ```typescript
 // src/pages/index.tsx
 
@@ -201,7 +209,6 @@ function App() {
 export default App;
 ```
 
-
 ## Usage
 
 ### Make a query
@@ -211,17 +218,18 @@ Use the `query` method to make one-off data requests and live subscriptions. Pas
 For example, pass `'application.context'` to retrieve details about the Marketplace app and the Sitecore host, including, for example, your Context IDs:
 
 ```typescript
-client.query("application.context")
+client
+  .query('application.context')
   .then((res) => {
-    console.log("Success retrieving application.context:", res.data);
+    console.log('Success retrieving application.context:', res.data);
     setAppContext(res.data);
   })
   .catch((error) => {
-    console.error("Error retrieving application.context:", error);
-});
+    console.error('Error retrieving application.context:', error);
+  });
 ```
 
-The application context provides information about your Marketplace app, such as its ID, URL, name, type, icon URL, installation ID, and associated resources:
+The application context provides information about your Marketplace app, such as its ID, URL, name, type, icon URL, installation ID, and associated resource access:
 
 ```javascript
 {
@@ -231,13 +239,13 @@ The application context provides information about your Marketplace app, such as
    url: 'https://my-app.com/app',
    iconUrl: 'https://my-app.com/assets/icon.png',
    installationId: 'abc1234567890',
-   resources: [
+   resourceAccess: [
      {
        resourceId: 'resource-1',
        tenantId: 'tenant-1',
        tenantName: 'Example Tenant',
        context: {
-         live: '1234567890', 
+         live: '1234567890',
          preview: '0987654321'
        }
      }
@@ -249,13 +257,13 @@ For an overview of all the possible values, refer to the [`QueryMap` interface](
 
 ### Make a mutation
 
-Use the `mutate` method to trigger changes in Sitecore (the host). Pass a value to the method depending on the change you want to make. 
+Use the `mutate` method to trigger changes in Sitecore (the host). Pass a value to the method depending on the change you want to make.
 
 For example, pass `'pages.reloadCanvas'` to reload the XM Cloud page builder canvas:
 
 ```typescript
 const reloadCanvas = () => {
-  client?.mutate("pages.reloadCanvas");
+  client?.mutate('pages.reloadCanvas');
 };
 ```
 
@@ -268,8 +276,10 @@ For an overview of all the possible values, refer to the [`MutationMap` interfac
 
 For more information, refer to the reference documentation in the `/docs` folder, and the official [Marketplace developer documentation](https://doc.sitecore.com/mp/en/developers/marketplace/introduction-to-sitecore-marketplace.html) and [Marketplace SDK documentation](https://doc.sitecore.com/mp/en/developers/sdk/latest/sitecore-marketplace-sdk/sitecore-marketplace-sdk-for-javascript.html).
 
-## License 
+## License
+
 This package is part of the Sitecore Marketplace SDK, licensed under the Apache 2.0 License. Refer to the [LICENSE](../../LICENSE.md) file in the repository root.
 
 ## Status
+
 The `client` package is actively maintained as part of the Sitecore Marketplace SDK.

packages/core/src/shared-types.ts

@@ -146,8 +146,12 @@ export interface ApplicationContext {
   iconUrl?: string;
   state?: string;
   installationId?: string;
+  /** @deprecated Use resourceAccess instead */
   resources?: ApplicationResourceContext[];
+  /** @deprecated Use extensionsPoints instead */
   touchpoints?: ApplicationTouchpointContext[];
+  resourceAccess?: ApplicationResourceContext[];
+  extensionsPoints?: ApplicationTouchpointContext[];
   [key: string]: any;
 }
 
@@ -165,8 +169,12 @@ export interface ApplicationRuntimeContext {
     state: string;
     [key: string]: any;
   };
+  /** @deprecated Use resourceAccess instead */
   resources: ApplicationResourceContext[];
+  /** @deprecated Use extensionsPoints instead */
   touchpoints: ApplicationTouchpointContext[];
+  resourceAccess?: ApplicationResourceContext[];
+  extensionsPoints?: ApplicationTouchpointContext[];
   [key: string]: any;
 }