Getting Started

The current state of the SDK is tested to work in zig 0.15.x

This Zig espocrm library provides an API client for EspoCRM. To get started you'll have to provide the URL where EspoCRM is located and your method of authentication. Read more from the official documentation.

Installation

Add this to your build.zig.zon

.dependencies = .{
    .espocrmz = .{
        .url = "https://github.com/definitepotato/espocrmz/archive/refs/heads/master.tar.gz",
        .hash = "the correct hash will be suggested by zig at build time",
    }
}

Add this to your build.zig

const espocrmz = b.dependency("espocrmz", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("espocrmz", espocrmz.module("espocrmz"));

You can then import the library into your code like this

const espocrm = @import("espocrmz");

Basic Usage

Using API Key Authentication:

const client: espocrm.Client = .init(
    "https://espocrm.example.com",
    .{ .api_key = "Your API Key here" },
);

Making a Read request:

const allocator = std.heap.page_allocator;

const result = try client.readEntity(
    allocator,
    "Contact",
    "78abc123def456",
);
defer result.deinit();

Making a List request:

const allocator = std.heap.page_allocator;

var params = espocrm.Parameters.init();
_ = params.setMaxSize(10).setOrder(espocrm.Parameters.Order.Asc);

var result = try client.listEntities(allocator, "Contact", params, &[_]espocrm.Where{
    .{ .filter_type = espocrm.FilterOption.Equals, .filter_attribute = "name", .filter_value = "Alice" },
    .{ .filter_type = espocrm.FilterOption.GreaterThan, .filter_attribute = "age", .filter_value = "42" },
});
defer result.deinit();

Paginating through all records with listEntitiesIterator:

listEntities returns a single page. Use listEntitiesIterator to iterate pages. It reads the total count from each response and stops when all records have been fetched.

const allocator = std.heap.page_allocator;

var params = espocrm.Parameters.init();
_ = params.setMaxSize(200);

var iter = client.listEntitiesIterator(allocator, "Contact", params, &[_]espocrm.Where{
    .{ .filter_type = espocrm.FilterOption.Equals, .filter_attribute = "status", .filter_value = "Active" },
});

while (try iter.next()) |page| {
    var p = page;
    defer p.deinit();
    // p.body contains the JSON for this page, e.g. {"total":1500,"list":[...]}
}

Listing related records with listRelatedEntities:

const allocator = std.heap.page_allocator;

var params = espocrm.Parameters.init();
_ = params.setMaxSize(20);

var result = try client.listRelatedEntities(
    allocator,
    "Account",        // entity type
    "67abe33f5883bd9e", // entity id
    "contacts",       // relationship link name
    params,
    &[_]espocrm.Where{},
);
defer result.deinit();

Paginating through all related records with listRelatedEntitiesIterator:

const allocator = std.heap.page_allocator;

var params = espocrm.Parameters.init();
_ = params.setMaxSize(200);

var iter = client.listRelatedEntitiesIterator(
    allocator,
    "Account",
    "67abe33f5883bd9e",
    "contacts",
    params,
    &[_]espocrm.Where{
        .{ .filter_type = espocrm.FilterOption.Equals, .filter_attribute = "title", .filter_value = "Manager" },
    },
);

while (try iter.next()) |page| {
    var p = page;
    defer p.deinit();
    // p.body contains the JSON for this page
}

Making a Create request:

const allocator = std.heap.page_allocator;

const new_contact =
  \\{
  \\  "name": "Alice",
  \\  "age": 69
  \\}
;

const result = try espocrm.createEntity(
    allocator,
    "Contact",
    new_contact,
);
defer result.deinit();

Making an Update request:

const allocator = std.heap.page_allocator;

const update_info =
  \\{
  \\  "name": "Bob"
  \\}
;

const result = try client.updateEntity(
    allocator,
    "Contact",
    "67abe33f5883bd9e",
    update_info,
);
defer result.deinit();

Making a Delete request:

const result = try client.deleteEntity(
    allocator,
    "Contact",
    "67abe33f5883bd9e",
);
defer result.deinit();