@stoody-official/stoodyapi-internal v0.11.5

Publishing Guidelines for stoodyapi-internal

Follow these steps to ensure the stoodyapi-internal package is published correctly while maintaining versioning and compatibility standards.

How to Install

Prerequisite: Paid npm Plan

As stoodyapi-internal is a private package, you’ll need an npm account with a paid plan to access and install it. If you’re not logged in to an authorized npm account, installation will fail.

Installation Steps

1. Log in to your npm account using the command:

   npm login

   Enter your username, password, and email when prompted (or use the link if it's automatically provided in your terminal).

2. Install the package:

   npm install @stoody-official/stoodyapi-internal

   or

   yarn add @stoody-official/stoodyapi-internal

3. Import the library in your project:

   import { StoodyAPIInternal, ApiVersionType, EnvironmentType } from "@stoody-official/stoodyapi-internal";
   
   class StoodyAPIInternalClient {
   private static instance: StoodyAPIInternal | null = null;
   
       private constructor() {}
   
       public static getInstance(): StoodyAPIInternal {
           if (!StoodyAPIInternalClient.instance) {
               if (!process.env.X_STOODY_API_VERSION ||
                   !process.env.X_STOODY_ENVIRONMENT ||
                   !process.env.X_STOODY_ENVIRONMENT_KEY) {
                   throw new Error('Missing required environment variables for StoodyAPI initialization');
               }
   
               StoodyAPIInternalClient.instance = new StoodyAPIInternal({
                   apiVersion: process.env.X_STOODY_API_VERSION as ApiVersionType,
                   environment: process.env.X_STOODY_ENVIRONMENT as EnvironmentType,
                   environmentKey: process.env.X_STOODY_ENVIRONMENT_KEY as string
               });
           }
   
           return StoodyAPIInternalClient.instance;
       }
   }
   
   // Prevent modifications to the class
   Object.freeze(StoodyAPIInternalClient);
   
   export default StoodyAPIInternalClient;

How to Publish

1. Verify TypeScript Code

Check for TypeScript issues to ensure the codebase is error-free:

tsc --noEmit

2. Thoroughly Test the Package

Testing ensures the reliability and correctness of the package. Follow these steps:

1. Set Up Jest Configuration: Ensure your jest.setup.ts is in the project root or a designated folder like tests. Configure Jest to load it:

   // jest.config.ts
   export default {
     setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
     testEnvironment: 'node', // Or another environment if required
   };

2. Run Unit Tests: Ensure all core functions and API interactions are covered by unit tests:

   npm test

3. Verify Edge Cases: Test for various edge cases, such as invalid API keys, network issues, or unexpected data formats.

4. Integration Testing: Validate the package's interaction with Stoody API endpoints in a staging or test environment to confirm compatibility.

3. Maintain API Compatibility

Since Stoody API endpoints are versioned:

• Reflect any changes to API endpoints in the updated functions.
• Deprecate outdated functions to maintain backward compatibility.
• If an API endpoint is no longer supported, update the package version according to the standard versioning policy.

4. Update Version Number

The stoodyapi-internal package follows semantic versioning (MAJOR.MINOR.PATCH):

• Patch (e.g., 0.0.1 → 0.0.2):

  • For minor fixes or security patches that don’t disrupt functionality.

• Minor (e.g., 0.0.2 → 0.1.0):

  • For backward-compatible feature additions.

• Major (e.g., 0.1.0 → 1.0.0):

  • For significant changes that may break compatibility or introduce major features.

Update the version field in package.json to reflect these changes.

5. Publish the Package

Once everything is verified:

1. Ensure you’re logged into your npm account:

   npm login

2. Build the package:

   npm run build

3. Change the version number:

   npm version <major|minor|patch>

   This command will update the version in package.json and create a new commit with the updated version.

4. Publish the package:

    npm publish --access restricted

5. Push the changes to the Git repository:

   git push --follow-tags

Important: Although we have a configuration set in the package.json to publish with --access restricted, it’s good practice to include it in the command to avoid any issues.

Unpublishing a Version

Due to npm’s unique versioning policy, published versions cannot be overwritten. If absolutely necessary, you can unpublish a specific version, but only for critical issues.

To unpublish a version (e.g., 0.0.1):

npm unpublish @stoody-official/stoodyapi-internal@0.0.1 --force

• Warning: Avoid unpublishing unless absolutely necessary, as it may disrupt users relying on that version.

Key Notes

• Ensure backward compatibility wherever possible.
• Increment the version number based on the nature and scope of changes.
• Use Jest to verify the functionality of all API-related operations.
• Thoroughly test before releasing to avoid buggy or incompatible updates.

By following these steps, you can ensure a smooth and professional publishing process for the stoodyapi-internal package.