Server SDKs

Taqlyn Server SDKs provide cryptographic link creation, parameter binding, and lifecycle routing for backend microservices and web servers. Unlike client-side mobile SDKs—which only use a public clientId and publicKeyId—server SDKs use asymmetric Ed25519 cryptographic signing with a private key to authenticate privileged operations.

Security Guardrail: The private key PEM (-----BEGIN PRIVATE KEY-----) must never be bundled into client-facing applications (iOS, Android, React Native, or web frontends). Keep it securely in your secret manager or environment variables.

#Installation

Install the official package for your runtime environment:

npm install @taqlyn/sdk-node
# or: pnpm add @taqlyn/sdk-node | bun add @taqlyn/sdk-node | yarn add @taqlyn/sdk-node

#Initialization

Initialize a shared client instance during service startup using your environment variables:

import { TaqlynClient } from "@taqlyn/sdk-node";

const taqlyn = new TaqlynClient({
  baseUrl: process.env.TAQLYN_BASE_URL || "https://api.taqlyn.com",
  clientId: process.env.TAQLYN_CLIENT_ID!,
  privateKey: process.env.TAQLYN_PRIVATE_KEY!,
});

#Configuration Parameters

Configure your backend server with three standard environment variables and optional transport settings:

#Creating Short Links

Generate short links programmatically during checkout, invite flows, user referral generation, or marketing campaigns:

const link = await taqlyn.createShortLink({
  destinationWeb: "https://myshop.com/products/42",
  destinationPath: "/products/42",
  params: {
    productId: "42",
    promoCode: "SUMMER30",
    referrer: "marketing_email",
  },
  mode: "deferred_app",
});

console.log("Short URL:", link.shortUrl);
console.log("Link ID:  ", link.id);

#Link Request Fields

When requesting a short link, configure the four primary routing properties:

#Available Routing Modes

• deferred_app: Standard universal deferred link. Attempts to open installed app; redirects to app store or web fallback if app is not installed.
• web_only: Always redirects to destinationWeb regardless of device or app installation status.
• app_only: Restricted strictly to installed mobile clients; returns an advisory fallback page on unsupported desktop platforms.

#Web Framework Integration

Integrate Taqlyn link creation directly into controllers, API routes, and dependency injection containers:

// Next.js Server Action: app/actions/invite.ts
"use server";

import { TaqlynClient } from "@taqlyn/sdk-node";

const taqlyn = new TaqlynClient({
  clientId: process.env.TAQLYN_CLIENT_ID!,
  privateKey: process.env.TAQLYN_PRIVATE_KEY!,
});

export async function createReferral(userId: string) {
  const link = await taqlyn.createShortLink({
    destinationWeb: `https://myapp.com/invite?from=${userId}`,
    destinationPath: "/invite/accept",
    params: { referrer: userId },
    mode: "deferred_app",
  });
  return link.shortUrl;
}

#Error Handling

When requests fail authentication, payload validation, or plan rate caps, the SDKs surface structured API exceptions:

import { TaqlynApiError } from "@taqlyn/sdk-node";

try {
  const link = await taqlyn.createShortLink(payload);
} catch (error) {
  if (error instanceof TaqlynApiError) {
    console.error("HTTP Status:", error.status); // e.g. 401, 403, 422
    console.error("Error Code: ", error.code);   // e.g. "INVALID_SIGNATURE"
    console.error("Message:    ", error.message);
  }
}

#Common Error Codes

#Kotlin & Java (JVM) Interoperability

The JVM SDK (com.taqlyn:sdk) is written in Kotlin and targets Java 17 bytecode. Java applications can call all APIs directly without needing Kotlin runtime adapters:

1. Both Kotlin DSL and Maven POM Supported: Works in modern Kotlin multiplatform builds and classic Maven Java enterprise stacks.
2. Dual-Accessor Architecture: Java callers can access fields using either Java 16+ record accessors (link.shortUrl()) or classic JavaBean getters (link.getShortUrl()).
3. Static Signer Methods: Cryptographic signing helpers use @JvmStatic, allowing Java classes to call Signer.loadPkcs8Pem(...) and Signer.signedHeaders(...) as regular static Java methods.
4. Unchecked Exceptions: Exceptions inherit from java.lang.RuntimeException, giving you the choice of try-catch blocks or higher-level framework exception handlers.