Skip to main content

Networking & Services

This section details the mutations available for managing networking and services on your Blocklet Server. You can perform actions such as configuring routing rules, managing SSL/TLS certificates, setting up webhooks, and handling notifications. For methods to retrieve networking and service data, please see the Networking & Services Queries section.

Routing Management

These mutations allow you to manage how traffic is routed to your blocklets and services.

addRoutingSite

Adds a new routing site, which is a collection of rules for a specific domain.

Parameters

  • input object (required) — An object containing the site details.
    • domain string (required) — The primary domain for the site.
    • type string (required) — The type of the site.
    • rules RoutingRuleInput[] — An array of routing rules to apply to this site.

Returns

  • ResponseRoutingSite object — The response object containing the newly created site.
    • code StatusCode — The status code of the operation.
    • site RoutingSite — The newly created routing site object.

Example

javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createRoutingSite() {
  try {
    const { site } = await client.addRoutingSite({
      input: {
        domain: 'example.com',
        type: 'blocklet',
        rules: [
          {
            from: { pathPrefix: '/' },
            to: { type: 'blocklet', did: 'z8iZuf...' },
          },
        ],
      },
    });
    console.log('Routing site created:', site.id);
  } catch (error) {
    console.error('Error creating routing site:', error);
  }
}

createRoutingSite();

addDomainAlias

Adds a domain alias to an existing routing site.

Parameters

  • input object (required) — An object containing the alias details.
    • id string (required) — The ID of the routing site to add the alias to.
    • domainAlias string (required) — The domain alias to add.
    • force boolean — Whether to force the addition even if conflicts exist.
    • teamDid string — The DID of the team associated with this action.

Returns

  • ResponseRoutingSite object — The response object containing the updated site.
    • code StatusCode — The status code of the operation.
    • site RoutingSite — The updated routing site object.

Example

javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function addAlias(siteId) {
  try {
    const { site } = await client.addDomainAlias({
      input: {
        id: siteId,
        domainAlias: 'www.example.com',
      },
    });
    console.log('Domain alias added:', site.domainAliases);
  } catch (error) {
    console.error('Error adding domain alias:', error);
  }
}

addAlias('z2as...'); // Replace with your site ID

deleteDomainAlias

Deletes a domain alias from a routing site.

Parameters

  • input object (required) — An object containing the details for deletion.
    • id string (required) — The ID of the routing site.
    • domainAlias string (required) — The domain alias to delete.
    • teamDid string — The DID of the team.

Returns

  • ResponseRoutingSite object — The response object containing the updated site.
    • code StatusCode — The status code of the operation.
    • site RoutingSite — The updated routing site object.

Example

javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function removeAlias(siteId) {
  try {
    const { site } = await client.deleteDomainAlias({
      input: {
        id: siteId,
        domainAlias: 'www.example.com',
      },
    });
    console.log('Domain alias removed:', site.domainAliases);
  } catch (error) {
    console.error('Error removing domain alias:', error);
  }
}

removeAlias('z2as...'); // Replace with your site ID

updateRoutingSite

Updates properties of an existing routing site, such as CORS allowed origins.

Parameters

  • input object (required) — An object containing the update details.
    • id string (required) — The ID of the routing site to update.
    • corsAllowedOrigins string[] — An array of allowed origins for CORS.
    • domain string — The new primary domain for the site.

Returns

  • ResponseRoutingSite object — The response object containing the updated site.
    • code StatusCode — The status code of the operation.
    • site RoutingSite — The updated routing site object.

Example

javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function updateSite(siteId) {
  try {
    const { site } = await client.updateRoutingSite({
      input: {
        id: siteId,
        corsAllowedOrigins: ['https://app.example.com'],
      },
    });
    console.log('Routing site updated:', site.id);
  } catch (error) {
    console.error('Error updating routing site:', error);
  }
}

updateSite('z2as...'); // Replace with your site ID

addRoutingRule

Adds a new routing rule to an existing site.

Parameters

  • input object (required) — An object containing the routing rule details.
    • id string (required) — The ID of the site to add the rule to.
    • rule RoutingRuleInput (required) — The routing rule object to add.

Returns

  • ResponseRoutingSite object — The response object containing the updated site.
    • code StatusCode — The status code of the operation.
    • site RoutingSite — The updated routing site object.

updateRoutingRule

Updates an existing routing rule within a site.

Parameters

  • input object (required) — An object containing the routing rule update details.
    • id string (required) — The ID of the site containing the rule.
    • rule RoutingRuleInput (required) — The updated routing rule object. The rule's id field must be provided.

Returns

  • ResponseRoutingSite object — The response object containing the updated site.
    • code StatusCode — The status code of the operation.
    • site RoutingSite — The updated routing site object.

deleteRoutingRule

Deletes a routing rule from a site.

Parameters

  • input object (required) — An object containing the identifiers for the rule to be deleted.
    • id string (required) — The ID of the site containing the rule.
    • ruleId string (required) — The ID of the rule to delete.

Returns

  • ResponseRoutingSite object — The response object containing the updated site.
    • code StatusCode — The status code of the operation.
    • site RoutingSite — The updated routing site object.

deleteRoutingSite

Deletes an entire routing site.

Parameters

  • input object (required) — An object containing the ID of the site to delete.
    • id string (required) — The ID of the routing site to delete.

Returns

  • GeneralResponse object — The response object indicating success or failure.
    • code StatusCode — The status code of the operation.

Example

javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function deleteSite(siteId) {
  try {
    await client.deleteRoutingSite({ input: { id: siteId } });
    console.log('Routing site deleted successfully.');
  } catch (error) {
    console.error('Error deleting routing site:', error);
  }
}

deleteSite('z2as...'); // Replace with your site ID

takeRoutingSnapshot

Creates a snapshot of the current routing configuration, which can be used for backup or rollback purposes.

Parameters

  • input object (required) — An object containing snapshot options.
    • dryRun boolean — If true, performs a dry run without creating the snapshot.
    • message string — A descriptive message for the snapshot.

Returns

  • ResponseTakeRoutingSnapshot object — The response object containing the snapshot hash.
    • code StatusCode — The status code of the operation.
    • hash string — The hash of the created snapshot.

Example

javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createSnapshot() {
  try {
    const { hash } = await client.takeRoutingSnapshot({
      input: { message: 'Backup before major update' },
    });
    console.log('Routing snapshot created with hash:', hash);
  } catch (error) {
    console.error('Error creating snapshot:', error);
  }
}

createSnapshot();

Certificate Management

Manage SSL/TLS certificates for your domains.

addCertificate

Adds a custom SSL/TLS certificate to the server.

Parameters

  • input object (required) — An object containing the certificate details.
    • name string (required) — A unique name for the certificate.
    • privateKey string (required) — The private key in PEM format.
    • certificate string (required) — The certificate chain in PEM format.

Returns

  • ResponseAddNginxHttpsCert object — The response object indicating success or failure.
    • code StatusCode — The status code of the operation.

Example

javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function uploadCertificate() {
  try {
    await client.addCertificate({
      input: {
        name: 'my-example-cert',
        privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
        certificate: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----',
      },
    });
    console.log('Certificate added successfully.');
  } catch (error) {
    console.error('Error adding certificate:', error);
  }
}

uploadCertificate();

issueLetsEncryptCert

Issues a new certificate from Let's Encrypt for a specified domain.

Parameters

  • input object (required) — An object containing the domain and associated site information.
    • domain string (required) — The domain to issue the certificate for.
    • did string (required) — The DID of the blocklet or team associated with this domain.
    • siteId string (required) — The ID of the routing site this certificate will be used for.

Returns

  • ResponseAddLetsEncryptCert object — The response object indicating success or failure.
    • code StatusCode — The status code of the operation.

Example

javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function issueCert(domain, did, siteId) {
  try {
    await client.issueLetsEncryptCert({
      input: {
        domain: domain,
        did: did,
        siteId: siteId,
      },
    });
    console.log(`Let's Encrypt certificate issuance initiated for ${domain}.`);
  } catch (error) {
    console.error('Error issuing certificate:', error);
  }
}

issueCert('example.com', 'z8iZuf...', 'z2as...');

updateCertificate

Updates the name of an existing custom certificate.

Parameters

  • input object (required) — An object containing the certificate update details.
    • id string (required) — The ID of the certificate to update.
    • name string (required) — The new name for the certificate.

Returns

  • ResponseUpdateNginxHttpsCert object — The response object indicating success or failure.
    • code StatusCode — The status code of the operation.

Example

javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function renameCertificate(certId) {
  try {
    await client.updateCertificate({
      input: {
        id: certId,
        name: 'new-cert-name',
      },
    });
    console.log('Certificate updated successfully.');
  } catch (error) {
    console.error('Error updating certificate:', error);
  }
}

renameCertificate('cert_xxx'); // Replace with your certificate ID

deleteCertificate

Deletes a custom SSL/TLS certificate from the server.

Parameters

  • input object (required) — An object containing the ID of the certificate to delete.
    • id string (required) — The ID of the certificate to delete.

Returns

  • ResponseDeleteNginxHttpsCert object — The response object indicating success or failure.
    • code StatusCode — The status code of the operation.

Example

javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function removeCertificate(certId) {
  try {
    await client.deleteCertificate({ input: { id: certId } });
    console.log('Certificate deleted successfully.');
  } catch (error) {
    console.error('Error deleting certificate:', error);
  }
}

removeCertificate('cert_xxx'); // Replace with your certificate ID

Webhook Management

Create and manage webhooks to receive notifications about events on your Blocklet Server.

createWebHook

Creates a new webhook sender configuration.

Parameters

  • input object (required) — An object containing the webhook details.
    • type SenderType (required) — The type of webhook sender (e.g., 'slack', 'api').
    • title string (required) — A title for the webhook.
    • description string — A description for the webhook.
    • params WebHookParamInput[] — An array of parameters for the webhook, such as the target URL.

Returns

  • ResponseCreateWebHook object — The response object containing the new webhook sender.
    • code StatusCode — The status code of the operation.
    • webhook WebHookSender — The created webhook sender object.

Example

javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createWebhook() {
  try {
    const { webhook } = await client.createWebHook({
      input: {
        type: 'api',
        title: 'My Custom Webhook',
        description: 'Sends notifications to my service.',
        params: [{ name: 'url', value: 'https://myservice.com/webhook' }],
      },
    });
    console.log('Webhook created:', webhook.id);
  } catch (error) {
    console.error('Error creating webhook:', error);
  }
}

createWebhook();

deleteWebHook

Deletes an existing webhook sender.

Parameters

  • input object (required) — An object containing the ID of the webhook to delete.
    • id string (required) — The ID of the webhook to delete.

Returns

  • ResponseDeleteWebHook object — The response object indicating success or failure.
    • code StatusCode — The status code of the operation.

Example

javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function deleteWebhook(webhookId) {
  try {
    await client.deleteWebHook({ input: { id: webhookId } });
    console.log('Webhook deleted successfully.');
  } catch (error) {
    console.error('Error deleting webhook:', error);
  }
}

deleteWebhook('wh_xxx'); // Replace with your webhook ID

createWebhookEndpoint

Creates a new webhook endpoint to receive events from the Blocklet Server.

Parameters

  • input object (required) — An object containing the webhook endpoint details.
    • teamDid string (required) — The DID of the team associated with this endpoint.
    • input WebhookEndpointStateInput (required) — The configuration for the new endpoint.

Returns

  • ResponseCreateWebhookEndpoint object — The response object containing the new webhook endpoint.
    • data WebhookEndpointState — The created webhook endpoint object.

Example

javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createEndpoint() {
  try {
    const { data } = await client.createWebhookEndpoint({
      input: {
        teamDid: 'z2qa...',
        input: {
          url: 'https://myapp.com/api/webhooks',
          description: 'My application endpoint',
          enabledEvents: [{ type: 'blocklet.started', source: 'system' }],
        },
      },
    });
    console.log('Webhook endpoint created:', data.id);
  } catch (error) {
    console.error('Error creating endpoint:', error);
  }
}

createEndpoint();

updateWebhookEndpoint

Updates an existing webhook endpoint.

Parameters

  • input object (required) — An object containing the webhook endpoint update details.
    • teamDid string (required) — The DID of the team.
    • id string (required) — The ID of the endpoint to update.
    • data WebhookEndpointStateInput (required) — The new configuration for the endpoint.

Returns

  • ResponseUpdateWebhookEndpoint object — The response object containing the updated webhook endpoint.
    • data WebhookEndpointState — The updated webhook endpoint object.

deleteWebhookEndpoint

Deletes a webhook endpoint.

Parameters

  • input object (required) — An object containing the ID of the endpoint to delete.
    • teamDid string (required) — The DID of the team.
    • id string (required) — The ID of the endpoint to delete.

Returns

  • ResponseDeleteWebhookEndpoint object — The response object containing the deleted webhook endpoint.
    • data WebhookEndpointState — The deleted webhook endpoint object.

retryWebhookAttempt

Retries a failed webhook delivery attempt.

Parameters

  • input object (required) — An object containing the details of the attempt to retry.
    • teamDid string (required) — The DID of the team.
    • eventId string (required) — The ID of the event.
    • webhookId string (required) — The ID of the webhook.
    • attemptId string (required) — The ID of the failed attempt.

Returns

  • ResponseGetWebhookAttempt object — The response object containing the new attempt state.
    • data WebhookAttemptState — The state of the new webhook attempt.

Notification Management

Manage user notifications within the Blocklet Server.

readNotifications

Marks one or more notifications as read.

Parameters

  • input object (required) — An object containing the notification IDs to mark as read.
    • notificationIds string[] (required) — An array of notification IDs.
    • teamDid string — The team DID scope.
    • receiver string — The receiver's DID.

Returns

  • ResponseReadNotifications object — The response object indicating the number of affected notifications.
    • code StatusCode — The status code of the operation.
    • numAffected number — The number of notifications marked as read.

Example

javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function markAsRead(notificationIds) {
  try {
    const { numAffected } = await client.readNotifications({
      input: { notificationIds: notificationIds },
    });
    console.log(`${numAffected} notifications marked as read.`);
  } catch (error) {
    console.error('Error marking notifications as read:', error);
  }
}

markAsRead(['notif_xxx', 'notif_yyy']);

unreadNotifications

Marks one or more notifications as unread.

Parameters

  • input object (required) — An object containing the notification IDs to mark as unread.
    • notificationIds string[] (required) — An array of notification IDs.
    • teamDid string — The team DID scope.
    • receiver string — The receiver's DID.

Returns

  • ResponseReadNotifications object — The response object indicating the number of affected notifications.
    • code StatusCode — The status code of the operation.
    • numAffected number — The number of notifications marked as unread.

Example

javascript
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function markAsUnread(notificationIds) {
  try {
    const { numAffected } = await client.unreadNotifications({
      input: { notificationIds: notificationIds },
    });
    console.log(`${numAffected} notifications marked as unread.`);
  } catch (error) {
    console.error('Error marking notifications as unread:', error);
  }
}

markAsUnread(['notif_xxx']);

This section covered mutations for networking and services. Next, you can explore mutations for managing backups and other operational tasks.

Next: Data & Operations

Learn how to perform mutations related to data management and operational tasks.

Read More