Skip to content

Commit 42fd2cb

Browse files
ogyamadaogyamada
committed
Say what you can do with this, and what to open an issue about
LICENSE is plain MIT now so GitHub can read it — the old hand-written mix showed up as no license at all, which is enough to stop a company using any of it. The data stays public domain on top; NOTICE.md spells that out. SECURITY.md documents what the API does with a request, since it asks people to POST live courier credentials. Issue forms for the three things worth reporting: a missing courier, a wrong commune, an API that misbehaved.
1 parent 4ea7303 commit 42fd2cb

10 files changed

Lines changed: 425 additions & 55 deletions

File tree

‎.github/ISSUE_TEMPLATE/api-problem.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
name: The API misbehaved
2+
description: A call to freeship.dzbuild.com did something it should not
3+
title: "API: "
4+
labels: ["api"]
5+
body:
6+
- type: textarea
7+
id: request
8+
attributes:
9+
label: The request
10+
description: >
11+
Curl or the JSON body, with credentials removed. Replace tokens with "…"
12+
— do not paste them, even expired ones.
13+
render: bash
14+
validations:
15+
required: true
16+
- type: textarea
17+
id: response
18+
attributes:
19+
label: The response
20+
description: Status code and body.
21+
render: json
22+
validations:
23+
required: true
24+
- type: input
25+
id: when
26+
attributes:
27+
label: Roughly when (with timezone)
28+
description: Requests are traced, so a timestamp is enough to find it.
29+
placeholder: 2026-08-26 14:30 UTC+1
30+
validations:
31+
required: true
32+
- type: textarea
33+
id: expected
34+
attributes:
35+
label: What you expected instead

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: true
2+
contact_links:
3+
- name: Security vulnerability
4+
url: https://github.com/DZBuild-com/dzship/blob/main/SECURITY.md
5+
about: Do not open an issue — email security@dzbuild.com.
6+
- name: API reference
7+
url: https://freeship.dzbuild.com
8+
about: Endpoints, fields, error codes and rate limits.

‎.github/ISSUE_TEMPLATE/courier-missing.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: A courier is missing
2+
description: Ask for an Algerian courier to be added
3+
title: "Add courier: "
4+
labels: ["courier"]
5+
body:
6+
- type: input
7+
id: courier
8+
attributes:
9+
label: Courier name
10+
description: The name on the contract, as merchants know it.
11+
placeholder: Rocket Delivery
12+
validations:
13+
required: true
14+
- type: input
15+
id: dashboard
16+
attributes:
17+
label: Dashboard URL
18+
description: >
19+
Where you log in to that courier. This usually answers which platform it
20+
runs on by itself — something.ecotrack.dz, for instance.
21+
placeholder: https://rocket.ecotrack.dz
22+
validations:
23+
required: true
24+
- type: dropdown
25+
id: platform
26+
attributes:
27+
label: Platform, if you know it
28+
options:
29+
- I don't know
30+
- Ecotrack
31+
- Yalidine
32+
- Procolis
33+
- Its own API
34+
validations:
35+
required: false
36+
- type: textarea
37+
id: extra
38+
attributes:
39+
label: Anything else
40+
description: >
41+
API documentation link, the credential fields their dashboard shows you,
42+
or which wilayas they cover. Never paste a token.

‎.github/ISSUE_TEMPLATE/data-fix.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: A commune or wilaya is wrong
2+
description: Report a wrong, missing or misspelled entry in the dataset
3+
title: "Data: "
4+
labels: ["data"]
5+
body:
6+
- type: input
7+
id: entry
8+
attributes:
9+
label: What is wrong
10+
placeholder: Commune "Ain Oussera" in wilaya 17
11+
validations:
12+
required: true
13+
- type: input
14+
id: expected
15+
attributes:
16+
label: What it should be
17+
description: >
18+
For a commune, the spelling the courier's own list uses — that is what
19+
makes the fix correct instead of a guess.
20+
validations:
21+
required: true
22+
- type: input
23+
id: source
24+
attributes:
25+
label: How you know
26+
description: >
27+
Which courier accepted or rejected it, or the Journal Officiel reference
28+
for a wilaya change.
29+
validations:
30+
required: true

‎CHANGELOG.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Changelog
2+
3+
## 2026-08-26
4+
5+
**92 couriers, each with its own key.** Every courier running on the Yalidine
6+
and Ecotrack platforms is now a first-class `courier` key — `dhd`, `conexlog`,
7+
`msmgo`, `rocketdelivery`, `yalitec`, `guepex`, `easyandspeed`, and 85 more.
8+
No tenant URL to look up: you name the courier, dzship keeps the address.
9+
`GET /v1/couriers?q=rocket` finds yours. The generic `ecotrack` key still works
10+
for a tenant we do not list yet, restricted to `*.ecotrack.dz`.
11+
12+
**New: `GET /v1/communes`.** All 1,541 communes, or one wilaya's with `?16`, or
13+
a search with `?q=bab`, in the spelling courier APIs expect.
14+
15+
**`GET /v1/wilayas` learned to answer questions**: `?16` for one wilaya,
16+
`?q=oran` to search in French or Arabic, `?all=1` for the full 2026 division.
17+
The default response is unchanged — the 58 wilayas couriers deliver to.
18+
19+
**Algeria's 2026 division, without breaking anyone.** Loi n° 26-06 of 4 April
20+
2026 created eleven new wilayas, numbered 59–69 by décret n° 26-206. No courier
21+
accepts a code above 58 yet, so the new wilayas are served only on request, each
22+
carrying the `shipAs` code to actually ship with. New datasets:
23+
`data/wilayas-2026.json`, `data/new-wilayas-2026.json`,
24+
`data/communes-moved-2026.csv`. ([#1](https://github.com/DZBuild-com/dzship/issues/1))
25+
26+
**Higher limits**: 200 orders/hour/IP (was 30), 1,000/day (was 100), 60 tracking
27+
calls/minute (was 30). Reference endpoints now send `Cache-Control` — cache them
28+
instead of polling.
29+
30+
**Docs**: a full [API reference](docs/endpoints.md) in the repo, the 82 Ecotrack
31+
couriers listed with their keys, and five dead links to a retired repository
32+
fixed.
33+
34+
## 2026-07-12
35+
36+
Integration clients for Node, PHP and Python, a per-stack integration guide, and
37+
`npm install dzship`. The API went worldwide — it had been Algeria-only.
38+
39+
## 2026-07-10
40+
41+
The wilaya and commune dataset: 58 wilayas, 1,541 communes, French + Arabic.
42+
43+
## 2026-07-08
44+
45+
First public release: the courier field guides and the free hosted API at
46+
freeship.dzbuild.com.

‎CONTRIBUTING.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Contributing
2+
3+
The service implementation is private; this repository holds the guides, the
4+
clients and the datasets. That still leaves the most valuable contributions
5+
open, because the things that break an Algerian shipping integration are facts,
6+
not code.
7+
8+
## The issues worth opening
9+
10+
**A courier is missing.** Tell us the courier's name and, if you know it, the
11+
platform it runs on (its dashboard URL is usually enough — `something.ecotrack.dz`
12+
answers the question by itself). Adding a courier that runs a platform we already
13+
speak takes minutes.
14+
15+
**A commune is wrong.** Wrong spelling, missing, or attached to the wrong
16+
wilaya. Say which courier rejected it and what spelling that courier's own list
17+
uses — that second half is what makes the fix correct rather than a guess.
18+
19+
**A status maps wrong.** If a courier reports a status that comes back as
20+
`unknown`, or one that means something different from what we mapped, send the
21+
raw status string and what actually happened to the parcel.
22+
23+
**A guide is out of date.** Couriers change endpoints without telling anyone.
24+
If a documented behaviour no longer matches reality, that is a bug in the guide.
25+
26+
**The API misbehaved.** Include the request you sent with credentials removed,
27+
the response you got, and the time — the traffic is traced, so a timestamp is
28+
enough to find it.
29+
30+
## Pull requests
31+
32+
Welcome for the guides, the clients and the datasets:
33+
34+
- **Guides** (`docs/`): keep the voice — direct, concrete, and about what
35+
actually happens. Prefer one accurate sentence to a paragraph of hedging. If
36+
you state a courier behaviour, say how you know.
37+
- **Clients** (`clients/`): they are deliberately dependency-free and boring.
38+
Node is CJS + ESM + types, PHP is one file with ext-curl only, Python is one
39+
file with the standard library only. Keep it that way — they get dropped into
40+
shared hosting and ten-year-old stacks.
41+
- **Datasets** (`data/`): a change needs a source. For communes, the source is
42+
the courier list that rejects or accepts the name. For wilayas, the source is
43+
the *Journal Officiel* — link the PDF and the article.
44+
45+
Run nothing, build nothing: there is no build step in this repository.
46+
47+
## What we will not merge
48+
49+
- A client that adds a dependency.
50+
- A dataset change without a source.
51+
- Anything that turns the guides into marketing.
52+
53+
## Security
54+
55+
Do not open an issue for a vulnerability — see [SECURITY.md](SECURITY.md).

‎LICENSE‎

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,21 @@
1-
Copyright (c) 2026 DZBuild (dzbuild.com). All rights reserved.
1+
MIT License
22

3-
The guides and documentation in this repository may be read, referenced,
4-
quoted, and used freely to build shipping integrations. Republishing them
5-
wholesale requires a link back to this repository.
3+
Copyright (c) 2026 DZBuild (https://dzbuild.com)
64

7-
The wilaya and commune datasets in the data/ directory describe public
8-
administrative facts and are dedicated to the public domain (CC0). Use them
9-
in any project, commercial or not, with no attribution required.
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
1011

11-
The client libraries in the clients/ directory are licensed under the MIT
12-
License: permission is hereby granted, free of charge, to any person obtaining
13-
a copy of those files, to deal in them without restriction, including without
14-
limitation the rights to use, copy, modify, merge, publish, distribute,
15-
sublicense, and/or sell copies, subject to no conditions. THE SOFTWARE IS
16-
PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
1714

18-
The freeship service (https://freeship.dzbuild.com) and its implementation
19-
are proprietary to DZBuild. No rights to the service implementation are
20-
granted.
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎NOTICE.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# What you may do with this
2+
3+
Everything in this repository — the guides, the clients and the datasets — is
4+
MIT licensed. See [LICENSE](LICENSE). Use it commercially, fork it, ship it in
5+
a closed product; no attribution required, though a link back is appreciated.
6+
7+
**The datasets go further.** The wilaya and commune files in [`data/`](data/)
8+
describe public administrative facts. They are additionally dedicated to the
9+
public domain under [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/):
10+
copy them into any project with no obligations whatsoever.
11+
12+
**The hosted service is not in this repository.** dzship
13+
([freeship.dzbuild.com](https://freeship.dzbuild.com)) — the courier adapters,
14+
the gateway and its infrastructure — is proprietary to DZBuild and is not
15+
distributed here. The MIT grant above covers the files you can see; it grants
16+
no rights to the service implementation.
17+
18+
The API itself is free to call, with the fair-use limits documented in
19+
[docs/endpoints.md](docs/endpoints.md#rate-limits). No signup, no key.

0 commit comments

Comments
 (0)