NG Connect SDK

Installation

Add the following script tag to your HTML file. The SDK is hosted on the NG CDN and is always kept up to date.

<script src="https://ng.net/sdk/ng-connect.js"></script>

After loading, the SDK exposes a global NG object with all platform capabilities. You can also use it as an ES module if you prefer:

// Download: https://ng.net/sdk/ng-connect.js
import NG from './ng-connect.js';

Quick Start

The following example shows a complete integration that detects NG Desktop, logs in the user, reads their stored preferences, and sends a notification.

<script src="https://ng.net/sdk/ng-connect.js"></script>
<script>
(async () => {
  // Step 1: Verify running inside NG Desktop
  try {
    await NG.ready();
  } catch (e) {
    // E001: app opened directly in browser, not via App Store
    console.warn(e.message);
    return;
  }

  // Step 2: Login / get user identity
  const user = await NG.auth.login();
  console.log('Hello,', user.display_name);

  // Step 3: Cloud storage
  const count = await NG.storage.get('visit_count') ?? '0';
  await NG.storage.set('visit_count', String(+count + 1));

  // Step 4: Adapt to system theme
  const theme = await NG.theme.get(); // 'dark' | 'light'
  document.body.dataset.theme = theme;

  // Step 5: Send a notification
  await NG.notify.send({
    title: 'Welcome back!',
    body: `You've visited ${+count + 1} times.`
  });
})();
</script>

NG.ready()

Use NG.ready() as the entry point for any NG Connect integration. It detects whether your app is running inside NG Desktop. If not, it rejects with error code E001, allowing you to handle the fallback gracefully.

try {
  await NG.ready();
  // Safe to use NG APIs here
} catch (e) {
  // E001: not running inside NG Desktop
  console.warn(e.message);
}

// Or synchronously:
if (NG.isAvailable()) {
  // inside NG Desktop
}

Also available as a synchronous check: NG.isAvailable() returns boolean.

NG.auth — User Authentication

The NG.auth module lets users sign in to your app using their NG Desktop account. No password or OAuth flow needed — the user simply approves your app's authorization request once, and subsequent calls return their identity silently.

const user = await NG.auth.login();
console.log(user.display_name, user.email);

NG.notify — Desktop Notifications

Send desktop-level notifications to the user via NG Desktop's notification system. Notifications appear in the NG Desktop interface even when the user is in another app.

await NG.notify.send({
  title: 'Upload complete',
  body: 'Your file has been saved successfully.',
  icon: 'https://myapp.com/icon.png'
});

NG.storage — Cloud Key-Value Storage

Per-app, per-user key-value cloud storage backed by Cloudflare D1. Use it to persist user preferences, app state, or any string data without building your own backend. Storage is isolated per app and per user.

await NG.storage.set('theme', 'dark');
const theme = await NG.storage.get('theme'); // 'dark'
await NG.storage.del('theme');

NG.social — Social Graph

Access the NG user follow graph. Build social features like friend activity feeds, collaborative workspaces, or multiplayer experiences on top of the NG social network.

NG.apps — App Management

Interact with the NG App Store from within your app. Open other apps or check what the user has installed.

NG.theme / locale / clipboard

Read system-level settings from NG Desktop to adapt your app's look and behavior.

const theme = await NG.theme.get();
document.body.classList.toggle('dark', theme === 'dark');

NG.ipc — Cross-App Communication

IPC (Inter-Process Communication) lets apps send and receive messages from each other within NG Desktop. Build ecosystems of cooperating apps — for example, a file picker app that sends selected files to another app.

// App A: send
await NG.ipc.send('file-picker', 'files:selected', { urls: ['...'] });

// App B: receive
NG.ipc.on('files:selected', (data, fromApp) => {
  console.log('Files from', fromApp, data.urls);
});

TypeScript Types

NG Connect SDK ships with the following core types:

interface User {
  id: string;           // NG user ID
  display_name: string; // User's display name
  email: string;        // User's email address
  avatar_url: string;   // Profile picture URL
}

interface AppInfo {
  slug: string; // App Store slug
  name: string; // App display name
}

// All SDK methods return Promises:
// NG.auth.login()          → Promise<User>
// NG.auth.getUser()        → Promise<User | null>
// NG.auth.logout()         → Promise<void>
// NG.notify.send(opts)     → Promise<void>
// NG.storage.get(key)      → Promise<string | null>
// NG.storage.set(k, v)     → Promise<void>
// NG.storage.del(key)      → Promise<void>
// NG.social.getFriends()   → Promise<User[]>
// NG.social.follow(id)     → Promise<void>
// NG.social.unfollow(id)   → Promise<void>
// NG.apps.open(slug)       → Promise<void>
// NG.apps.getInstalled()   → Promise<AppInfo[]>
// NG.theme.get()           → Promise<'light' | 'dark'>
// NG.locale.get()          → Promise<string>
// NG.clipboard.write(text) → Promise<void>
// NG.ipc.send(slug, ev, d) → Promise<void>
// NG.ipc.on(ev, handler)   → void

Error Codes

SDK errors follow the format [NG Connect E001] Description.

Frequently Asked Questions