@ductape/client
v0.0.6
Published
Frontend client SDK for Ductape - real-time database, storage, and more
Maintainers
Readme
@ductape/client
Frontend SDK for Ductape. Access databases, storage, APIs, agents, brokers, and more directly from the browser.
Install
npm install @ductape/client@latestSetup
import { createClient } from '@ductape/client';
const ductape = createClient({
publishableKey: import.meta.env.VITE_PUBLISHABLE_KEY,
product: 'my-product',
env: 'prd',
});Publishable-key operations use the Ductape proxy. Your backend issues the session token after login; supply it as config.session or call ductape.setSession(token). An explicit operation-level session overrides the configured token. ductape.setSession(undefined) clears it on logout. The server remains responsible for enforcing protected-operation permissions. Do not disable session enforcement to enable login; use your backend login endpoint or an explicitly permitted pre-login operation.
Changing the session closes existing realtime streams. Call connect() again to establish streams under the new identity. The client forwards the session in subscription payloads, not URLs; each deployed gateway must enforce authorization for its resource types.
Product/environment scope is immutable after any service is accessed. Create a new client when switching scope, and dispose the old client's connections. Before services are accessed, setProduct() and setEnv() remain available.
Execution and retry safety
Feature execution returns the server receipt, including feature_id, execution_time, and step results. executionId is a compatibility alias for feature_id; absent timestamps are not fabricated. Failed, rolled-back, or cancelled executions throw FEATURE_EXECUTION_FAILED, with the receipt on error.result. HTTP success alone does not imply business success.
Single-channel notification failures also reject. multiChannel() reports independent per-channel success/failure results. Notifications use the shared transport and configured session.
POST, PUT, PATCH, and DELETE requests are not automatically retried, including POST-based proxy operations. A timeout can mean the write committed: reconcile its outcome before replaying it. Only GET/HEAD/OPTIONS transport failures receive automatic retries. Supplying an arbitrary idempotency field does not establish server deduplication support.
Real-time
Call connect() before using any subscription feature:
await ductape.connect();
ductape.onConnectionChange((event) => {
console.log(event.state); // 'connecting' | 'connected' | 'disconnected' | 'error'
});
ductape.disconnect();Services
Databases
const sessionToken = getSessionFromYourBackend();
const result = await ductape.databases.query({
database: 'orders-db',
table: 'orders',
where: { status: 'pending' },
limit: 20,
session: sessionToken,
});
await ductape.databases.insert({
database: 'orders-db',
table: 'orders',
data: { userId: '123', amount: 4900 },
session: sessionToken,
});
await ductape.databases.update({
database: 'orders-db',
table: 'orders',
where: { id: 'abc' },
data: { status: 'shipped' },
session: sessionToken,
});
await ductape.databases.delete({
database: 'orders-db',
table: 'orders',
where: { id: 'abc' },
session: sessionToken,
});
// Real-time row changes
const sub = ductape.databases.subscribe(
{ database: 'orders-db', table: 'orders', session: sessionToken },
(changes) => console.log(changes)
);
sub.unsubscribe();Third-party API actions
// Register OAuth credentials for automatic token refresh
await ductape.api.oauth({
product: 'my-product',
app: 'salesforce',
env: 'prd',
tokens: { accessToken: userAccessToken, refreshToken: userRefreshToken },
expiresIn: 3600,
credentials: (tokens) => ({
'headers:Authorization': `Bearer ${tokens.accessToken}`,
}),
onExpiry: async (currentTokens) => {
const res = await ductape.api.run({
app: 'salesforce',
action: 'refresh-token',
input: { 'body:refresh_token': currentTokens.refreshToken },
session: sessionToken,
});
return { tokens: { accessToken: res.data.access_token }, expiresIn: res.data.expires_in };
},
});
const result = await ductape.api.run({
app: 'salesforce',
action: 'get-contacts',
session: sessionToken,
});Storage
await ductape.storage.upload({
storage: 'receipts',
fileName: 'invoice-001.pdf',
data: fileBlob,
mimeType: 'application/pdf',
session: sessionToken,
});
const file = await ductape.storage.download({ storage: 'receipts', fileName: 'invoice-001.pdf', session: sessionToken });
const list = await ductape.storage.list({ storage: 'receipts', session: sessionToken });
const url = await ductape.storage.signedUrl({ storage: 'receipts', fileName: 'invoice-001.pdf', expiresIn: 3600, session: sessionToken });Cache
await ductape.cache.set({ cache: 'app-cache', key: 'config', value: { theme: 'dark' }, ttl: 3600, session: sessionToken });
const entry = await ductape.cache.get({ cache: 'app-cache', key: 'config', session: sessionToken });
await ductape.cache.del({ cache: 'app-cache', key: 'config', session: sessionToken });Agents
const result = await ductape.agents.run({
agent: 'support-bot',
input: 'How do I reset my password?',
session: sessionToken,
});
// Streaming
const stream = await ductape.agents.stream({ agent: 'support-bot', input: 'Summarise my account.', session: sessionToken });
for await (const event of stream) {
if (event.type === 'token') process.stdout.write(event.data);
}Features
const run = await ductape.features.execute({
feature: 'process-order',
input: { orderId: 'ord_123' },
session: sessionToken,
});
const status = await ductape.features.status({
feature: 'process-order',
executionId: run.executionId,
session: sessionToken,
});
const sub = ductape.features.subscribe(
{ feature: 'process-order', executionId: run.executionId, session: sessionToken },
(events) => console.log(events)
);
sub.unsubscribe();Brokers
await ductape.brokers.publish({
broker: 'kafka-cluster',
topic: 'order-events',
message: { orderId: 'ord_123', event: 'created' },
session: sessionToken,
});
const sub = ductape.brokers.subscribe(
{ broker: 'kafka-cluster', topic: 'order-events', session: sessionToken },
(messages) => console.log(messages)
);
sub.unsubscribe();Vectors
const results = await ductape.vectors.query({
vector: 'product-embeddings',
query: [0.1, 0.2, 0.85],
topK: 5,
session: sessionToken,
});Graphs
const node = await ductape.graphs.createNode({
graph: 'social-graph',
label: 'User',
properties: { name: 'Alice', age: 30 },
session: sessionToken,
});Warehouse
const result = await ductape.warehouse.query({
query: 'SELECT * FROM orders WHERE status = :status',
params: { status: 'pending' },
sources: [{ database: 'orders-db', tables: ['orders'] }],
session: sessionToken,
});Resilience
const quota = await ductape.resilience.quota.run({ tag: 'api-rate-limit', session: sessionToken });
const health = await ductape.resilience.health.status({ tag: 'payment-service', session: sessionToken });Notifications
await ductape.notifications.push.send({
notification: 'order-shipped',
input: { orderId: 'ord_123', userId: 'usr_456' },
session: sessionToken,
});Analytics
// Anonymous tracking — no session needed before login
await ductape.analytics.track({ event: 'page_view', properties: { page: '/home' } });
// Link to a session after login
ductape.analytics.identify(sessionToken);
await ductape.analytics.track({ event: 'purchase', properties: { amount: 4900 } });