oci-ons

library2.132.0jsnpmunverified

The official Oracle Cloud Infrastructure SDK module for the ONS (Oracle Notification Service) in Node.js. Version 2.132.0 is the latest stable release, part of the oci-typescript-sdk monorepo. This package provides programmatic access to ONS topics and subscriptions. It is maintained by Oracle and follows the monthly SDK release cadence. Key differentiators: first-class TypeScript support, use with OCI authentication providers (config file, instance principals, resource principals), and support for both ESM and CommonJS. It requires the oci-common package for authentication and configuration.

messaging

npm install oci-ons

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OCI-ONS

oci-ons

messagingjavascriptv2.132.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

OnsClient

✓ import { OnsClient } from 'oci-ons'; const client = new OnsClient({ authenticationDetailsProvider: provider });

✗ const { OnsClient } = require('oci-ons'); const client = new OnsClient(); // missing authenticationDetailsProvider

ESM import; requires an authentication provider created with oci-common.

models (namespace)

✓ import * as models from 'oci-ons/lib/models'; const topic = models.NotificationTopic;

✗ const models = require('oci-ons').models;

Models are exported as a namespace; always use named imports for specific types.

requests (namespace)

✓ import * as requests from 'oci-ons/lib/requests'; const req = requests.CreateTopicRequest;

✗ const requests = require('oci-ons').requests;

Request types are exported as a namespace; useful for TypeScript.

Initialize ONS client with config file auth and list topics in a compartment.

import { OnsClient } from 'oci-ons'; import { ConfigFileAuthenticationDetailsProvider } from 'oci-common'; const provider = new ConfigFileAuthenticationDetailsProvider(); const client = new OnsClient({ authenticationDetailsProvider: provider }); async function listTopics() { const listTopicsRequest = { compartmentId: process.env.COMPARTMENT_ID }; const response = await client.listTopics(listTopicsRequest); console.log(response.items); } listTopics().catch(console.error);

Debug

Known issues

breakingIn version 2.0.0, the SDK migrated from CommonJS to hybrid ESM/CJS. Dynamic require() may fail.

fix

Use import syntax or ensure CJS interop. If using require(), use: const { OnsClient } = require('oci-ons').default; or use dynamic import().

affects: >=2.0.0

deprecatedThe 'oci-ons' package version 1.x is deprecated and no longer receives updates.

fix

Upgrade to version 2.x: npm install oci-ons@latest

affects: >=1.0.0 <2.0.0

gotchaOnsClient constructor requires authenticationDetailsProvider. Omitting it leads to cryptic errors about missing region.

fix

Always pass a valid authentication provider from oci-common, e.g., ConfigFileAuthenticationDetailsProvider or InstancePrincipalsAuthenticationDetailsProvider.

affects: >=2.0.0

gotchaTopic and subscription creation may fail silently if IAM policies are insufficient.

fix

Ensure the user or instance has proper IAM policies for ons topic and subscription management.

affects: >=2.0.0

gotchaThe SDK uses async/await; callbacks are not supported. Mixed use of promises and callbacks will cause unhandled promise rejections.

fix

Always handle promises with async/await or .catch().

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: client.listTopics is not a function

OnsClient was imported incorrectly or as a default export but then used as a function.

fix

Use named import: import { OnsClient } from 'oci-ons'; and instantiate with 'new'.

Error: Missing region in config

Authentication provider configuration file lacks region, or region is not set in environment.

fix

Ensure your OCI config file (~/.oci/config) contains a region entry, or set the OCI_REGION environment variable.

Cannot find module 'oci-common'

The 'oci-common' peer dependency is not installed.

fix

npm install oci-common

Error: ENOENT: no such file or directory, open '/root/.oci/config'

OCI config file is missing at default location.

fix

Create the OCI config file at ~/.oci/config or use a different authentication provider (e.g., InstancePrincipalsAuthenticationDetailsProvider).

Upgrade

Version history

2.132.0latest on npm

Audit

Dependencies

oci-commonrequiredRequired for authentication, configuration, and HTTP handling

Agent activity

12 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/oracle/oci-typescript-sdk ↗

packageoci-ons ↗

homepagehttps://github.com/oracle/oci-typescript-sdk#readme ↗