{"id":14965393,"url":"https://github.com/keslerm/salt-net-api","last_synced_at":"2025-04-04T09:29:00.734Z","repository":{"id":46104002,"uuid":"404875526","full_name":"keslerm/salt-net-api","owner":"keslerm","description":"This is a mirror of https://codeberg.org/rridley/salt-net-api","archived":false,"fork":false,"pushed_at":"2022-06-02T18:04:19.000Z","size":201,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-01T21:33:54.110Z","etag":null,"topics":["saltstack","typescript-library"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/keslerm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-09-09T21:32:00.000Z","updated_at":"2025-03-10T12:57:46.000Z","dependencies_parsed_at":"2022-09-03T06:52:35.904Z","dependency_job_id":null,"html_url":"https://github.com/keslerm/salt-net-api","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keslerm%2Fsalt-net-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keslerm%2Fsalt-net-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keslerm%2Fsalt-net-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keslerm%2Fsalt-net-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/keslerm","download_url":"https://codeload.github.com/keslerm/salt-net-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247152223,"owners_count":20892457,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["saltstack","typescript-library"],"created_at":"2024-09-24T13:34:40.937Z","updated_at":"2025-04-04T09:29:00.704Z","avatar_url":"https://github.com/keslerm.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Salt Net API\n\nSalt Net API is a TypeScript client for SaltStack to add essential type checking and validation, as well as make working the somewhat convoluted\ndata structures of SaltStack much easier.\n\nThis library heavily utilizes types to provide a clean interface for interacting with minimal logical code to manage.\n\n## Missing Types\n\nSaltStack has an extremely expansive amount of functions and modules available. Initially, I'm mostly adding them as I need manually and\nthus providing a way for you to easily extend types that are missing.\n\nI welcome PRs to add more typings around more functions.\n\nEventually when things look more solid I might generate these automatically from the Salt API documentation.\n\n## Using This Client\n\nThis client provides a few abstractions around the matching Salt clients.\n\n```typescript\nimport { LocalClient, WheelClient, Core, Modules, Runner } from \"salt-net-api\";\n\n// Create a connection to the Local salt client\nexport const local = new LocalClient({\n  endpoint: process.env.SALT_ENDPOINT!,\n  username: process.env.SALT_USERNAME!,\n  password: process.env.SALT_PASSWORD!,\n  eauth: \"file\",\n});\n\n// Define the request type and the expected response type.\nconst a2 = await local.exec\u003cModules.Test.IPingRequest, Modules.Test.IPingResult\u003e({\n  fun: \"test.ping\",\n  tgt: \"test-site\",\n});\n\n// You can also execute against the async client where available\nconst asyncResponse: Core.ILocalAsyncResponse = await local.execAsync\u003cModules.Service.IRestartRequest\u003e({\n  fun: \"service.restart\",\n  kwarg: {\n    // The type inference will validate that you are passing this required argument\n    name: \"service-name\",\n  },\n});\n\n// Other clients are also available\nexport const wheel = new WheelClient({\n  endpoint: process.env.SALT_ENDPOINT!,\n  username: process.env.SALT_USERNAME!,\n  password: process.env.SALT_PASSWORD!,\n  eauth: \"file\",\n});\n\n// This also works for other clients\nconst a1 = await wheel.exec\u003cRunner.Key.IListRequest, Runner.Key.IListResponse\u003e({\n  fun: \"key.list\",\n  match: \"pre\",\n});\n\n// If a type is missing you can easily specify it yourself\ninterface INginxStatusRequest extends Core.ILocalRequest {\n  kwarg: {\n    url: string;\n  }\n}\ninterface INginxStatusResponse {\n  [key: string]: {\n    connections: number;\n    status: boolean;\n  }\n}\n\nconst customTypeResponse = await local.exec\u003cINginxStatusRequest, INginxStatusResponse\u003e({\n  fun: \"nginx.status\",\n  kwarg: {\n    url: \"http://localhost\",\n  }\n});\n```\n\n## Events Client\n\nThe SaltStack Event Bus is an incredibly useful tool for building event driven automation and functionality from. The events client allows you to easily\nleverage this functionality.\n\n```typescript\nimport { EventsClient } from 'salt-net-api';\n\nconst client = new EventsClient({\n  endpoint: process.env.SALT_ENDPOINT!,\n  username: process.env.SALT_USERNAME!,\n  password: process.env.SALT_PASSWORD!,\n  eauth: \"file\",\n});\n\nclient.subscribe({\n  tag: \"salt/auth\",\n  handler: (event: any) =\u003e {\n    console.log(event);\n  }\n});\n\nawait client.start();\n```\n\n## Why\n\nI wanted to create a way to easily interact with the SaltStack Net API while also taking advantage of TypeScript's ability to type things to make\nit have access to required argument validation and auto completion. The SaltStack API has a massive amount of formatting and data differences between\nmodules and even within a single module.\n\nOriginally I started by implementing functions within each client type for every module but it very quickly became far too much essentially boiler plate\ncode that was just really wrapping types and executing a simple request.\n\nEventually I deprecated that version and decided to almost entirely rely on TypeScript's ability to type check and generics. This minimizes the amount\nof code that actually needs to be unit tested, thus making everything much simpler. It also makes it easy for people to easy create their own types\nfor modules that may be missing, or custom modules. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeslerm%2Fsalt-net-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeslerm%2Fsalt-net-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeslerm%2Fsalt-net-api/lists"}